README Robert Duncan, March 1996
Using Poplog 15.01 on Windows NT
================================
This file provides a review of features specific to Win32 Poplog which
are not yet described in the online documentation.
See also REF * SYSUTIL which describes Poplog interfaces to some Win32
functions.
*** NB: none of these features are guaranteed to remain the same
*** in future releases
For guidance on running Poplog, see the section REF * SYSTEM below.
CONTENTS - (Use <ENTER> g to access required sections)
-- REF * ASYNC
-- REF * EXTERNAL
-- REF * POPC
-- REF * SYSIO
-- REF * SYSTEM
-- REF * TIMES
-- REF * ASYNC --------------------------------------------------------
All asynchronous events are disabled while Poplog is performing I/O.
Time-consuming I/O operations, such as reading from pipes and
communications devices, can arbitrarily delay the handling of timers,
etc. This is most noticeable when running as a console application:
while waiting for console input, Poplog will not respond to any
asynchronous events other than those which are console-related.
INCLUDE * SIGDEFS defines the following signals for Win32:
SIG_HUP
SIG_INT
SIG_QUIT
SIG_ILL
SIG_EXN
SIG_CHLD
SIG_ALRM
SIG_FPE
SIG_BUS
SIG_SEGV
SIG_TERM
Of these, however, all but SIG_HUP and SIG_TERM are handled specially by
Poplog and the behaviour cannot be changed.
Typing Ctrl+C at the console generates SIG_INT while Ctrl+Break
generates SIG_QUIT. Currently, however, both of these are treated the
same and will both call interrupt(). A console interrupt generated while
Poplog is waiting for console input can terminate the process.
Use Ctrl+Break to interrupt Poplog from the Ved window.
-- REF * EXTERNAL -----------------------------------------------------
External load can extract names only from dynamic link libraries (DLLs).
The input_file_list argument to exload can contain only DLL names. If a
DLL name has no pathname component, it is sought first in the directory
from which Poplog was loaded, then in the current directory, then in the
standard Windows DLL directories and finally in those directories
specified in the PATH environment variable. The '.dll' extension is
added automatically to the name where necessary.
For example, to load the Win32 function GetCommandLine:
exload win32 [kernel32]
GetCommandLine() : exval#exval_to_string <- GetCommandLineA,
endexload;
exacc GetCommandLine() =>
** d:\win32app\poplog\15.01\pop\pop\winpop11.exe +startup
Note that when loading Win32 functions you must specify the ANSI (A) or
UNICODE (W) versions explicitly as needed (NB: Poplog cannot interpret
UNICODE strings).
External DLLs which need to do callback into Poplog must be linked
against the import library
$usepop/pop/pop/poplog.lib
-- REF * POPC ---------------------------------------------------------
Popc is not supported under Win32.
-- REF * SYSIO --------------------------------------------------------
The org argument supplied to sysopen, syscreate, etc. is interpreted
similarly to Unix, but with the following variations:
Windows text files traditionally use the CR-LF character pair to
indicate the end of a line and ^Z to indicate end of file. Files can be
opened in either text or binary mode. In text mode, each CR-LF pair is
mapped on input to a single LF character, while LF on output is mapped
to CR-LF; ^Z is used to indicate end-of-file in both directions. In
binary mode, all characters are read and written without interpretation.
In Win32 Poplog, text or binary mode is selected through the org
argument as follows:
org mode
--- ----
false text
"line" text
"record" binary
true binary
In addition, if the file is a console input or screen buffer, any org
other than false interacts with the console in 'raw' mode.
Currently, back versions of files are maintained in the Unix style, i.e.
with '-' characters appended to the file name (NB: this can confuse File
Manager selections and may be changed in the future).
syspipe is supported as on Unix and creates a Win32 anonymous pipe. Pipe
I/O is non-interruptable: reading from a pipe connected to a hung
process will also hang Poplog and cannot be interrupted. When the output
end of a pipe is passed to sys_create_process, the handle for that
device is duplicated into the new process: this means there will be two
handles open for output to the pipe. A read from the pipe will not
terminate with end-of-file until both those handles have been closed.
Typically, then, you will want to close the pipe output device still
held by Poplog -- and hence its associated handle -- AFTER creating the
sub-process but BEFORE trying to read from the pipe's input device.
Failure to do so is a guaranteed way of hanging your Poplog process for
good. Similar considerations apply also to writing to a process through
a pipe.
sys_file_stat is supported for compatibility with other systems but
returns only the first two fields of output, i.e.
Subscript Information Returned
--------- --------------------
1 Size of file in bytes
2 Last modified time
The last modified time is expressed in Unix time, i.e. as a number of
seconds since 00:00 January 1, 1970; it can be converted to a printable
date using sys_convert_date.
Asynchronous I/O is not supported.
-- REF * SYSTEM -------------------------------------------------------
Win32 Poplog provides just two executable commands
pop11.exe -- base Console application
winpop11.exe -- base GUI application
These are found in $usepop/pop/pop, the traditional 'popsys' directory;
you should add this directory to your PATH if you want to run these
commands from the Command Prompt.
To run a standard Poplog, use
pop11 +startup
and for each of the languages add the appropriate image name -- prolog,
clisp or pml -- as follows:
pop11 +startup +clisp
The standard command-line arguments are supported, except for %x.
The Poplog program group contains sample program items for running
Poplog. The 'Pop-11' item runs Pop-11 in a console window; the 'Ved'
item runs Pop-11 in a Ved window. To run other languages, copy one or
other program item and change the command line to include the
appropriate language image.
There is no separate 'popsavelib' directory for saved images: these are
placed by default in the 'popsys' directory with the executables.
sys_host_id returns the OEM machine ID from the Win32 GetSystemInfo
call.
sys_host_name returns the local computer name obtained from the Win32
GetComputerName call.
sys_machine_type returns the list
[pc]
sys_os_type returns the list
[windows nt 3.51]
sys_processor_type returns the list
[80386]
INCLUDE * SYSDEFS defines the macros:
PC
WINDOWS
WINDOWS_NT
WIN32
-- REF * TIMES --------------------------------------------------------
sys_convert_date and sysdaytime return date strings in the format
DD/MM/YYYY HH:MM:SS
For example:
sysdaytime() =>
** 19/03/1996 11:41:52