DAY_OF_WEEK, CVT_FROM_INTERNAL_TIME, and SPAWN

In the previous article, we used some new system services. Let's document them here.

LIB_DAY_OF_WEEK

Returns the numeric day of the week for a supplied time stamp.

Format

LIB_DAY_OF_WEEK time, result

Arguments

time
A pointer to a 64-bit timestamp. If 0, the current system time is used.

result
A pointer to a 64-bit integer to receive the day number.

Description

This service returns the number of the day of the week corresponding to the passed time. If 0 is passed for the time, the current system time is used. The days are numbered 1 through 7, with Monday having the value 1.

Condition Values Returned

SS_NORMAL Normal completion of service.

CVT_FROM_INTERNAL_TIME

Converts a timestamp into human-centric values.

Format

LIB_CVT_FROM_INTERNAL_TIME result, operation {, time}

Arguments

operation
A pointer to a 64-bit integer value indicating the conversion to perform, as defined by the following:

Mneumonic Value Result range Description

LIB_K_MONTH_OF_YEAR 0 1 to 12 Month: January=1

LIB_K_DAY_OF_YEAR 1 1 to 366 Day of year

LIB_K_HOUR_OF_YEAR 2 1 to 8,784 Hour of year

LIB_K_MINUTE_OF_YEAR 3 1 to 527,040 Minute of year

LIB_K_SECOND_OF_YEAR 4 1 to 31,622,400 Second of year

LIB_K_DAY_OF_MONTH 5 1 to 31 Day of month

LIB_K_HOUR_OF_MONTH 6 1 to 744 Hour of month

LIB_K_MINUTE_OF_MONTH 7 1 to 44,640 Minute of month

LIB_K_SECOND_OF_MONTH 8 1 to 2,678,400 Second of month

LIB_K_DAY_OF_WEEK 9 1 to 7 Day of week. Monday=1

LIB_K_HOUR_OF_WEEK 10 1 to 168 Hours since midnight of previous Monday

LIB_K_MINUTE_OF_WEEK 11 1 to 10,080 Minutes since midnight of previous Monday

LIB_K_SECOND_OF_WEEK 12 1 to 604,800 Seconds since midnight of previous Monday

LIB_K_HOUR_OF_DAY 13 0 to 23 Hour of day

LIB_K_MINUTE_OF_DAY 14 0 to 1,439 Minute of day

LIB_K_SECOND_OF_DAY 15 0 to 86,399 Second of day

LIB_K_MINUTE_OF_HOUR 16 0 to 59 Minute of hour

LIB_K_SECOND_OF_HOUR 17 0 to 3,599 Second of hour

LIB_K_SECOND_OF_MINUTE 18 0 to 59 Second of minute

LIB_K_NANOSECOND_OF_SECOND 18 0 to 999,999,999 Nanosecond of second

LIB_K_JULIAN_DATE 19 Days since 17-Nov-1858

LIB_K_DELTA_WEEKS 20 Number of whole weeks represented by delta time

LIB_K_DELTA_DAYS 21 Number of whole days represented by delta time

LIB_K_DELTA_HOURS 22 Number of whole hours represented by delta time

LIB_K_DELTA_MINUTES 23 Number of whole minutes represented by delta time

LIB_K_DELTA_SECONDS 24 Number of whole seconds represented by delta time

The last five conversions interpret the time as a delta time; the rest interpret the time as absolute.

result
A pointer to a 64-bit integer to receive the conversion result.

time
A pointer to a 64-bit timestamp. If 0, the current system time is used.

Description

This service returns a number which is the conversion of an absolute or delta time using the specified operation.

Condition Values Returned

SS_NORMAL Normal completion of service.
LIB_ABSTIMREQ Absolute time required but delta time supplied.
LIB_INVOPER Invalid operation.

SPAWN

Spawns a subprocess.

Format

LIB_SPAWN {command} {,input} {,output} {,flags} {,name} {,pid} {,status} {,eventflag} {,AST} {,ASTP} {,prompt} {,shell} {,reserved}

Arguments

command
A pointer to an SRB which points to the name of the program to execute in the subprocess. If this parameter is 0, the default or specified shell is executed in interactive mode. This string can also contain parameters after the program name in order to pass those parameters to the program.

input
A pointer to an SRB which points to the name of the file to be assigned to sys$input in the subprocess. If this is 0, the subprocess uses the same sys$input as the calling process.

output
A pointer to an SRB which points to the name of the file to be assigned to sys$output in the subprocess. If this is 0, the subprocess uses the same sys$output as the calling process.

flags
A pointer to a 64-bit integer containing options for subprocess creation, as follows. If this parameter is 0, the flags are considered to all be unset.

Mnuemonic Value Description

CLI_M_NOWAIT 1 If set, the calling process continues executing asynchronously. Otherwise the calling process is blocked until the subprocess finishes.

CLI_M_NOCLISYM 2 The spawned subprocess does not inherit symbols.

CLI_M_NOLOGNAM 4 The spawned subprocess does not inherit symbols. This has the same meaning as CLI_M_NOCLISYM.

CLI_M_NOKEYPAD 8 The keypad symbols and state are not passed to the subprocess.

CLI_M_NOTIFY 16 A message is broadcast to sys$output when the subprocess completes or aborts.

CLI_M_NOCONTROL 32 No carriage-return/line-feed is prefixed to any prompt string on the subprocess.

CLI_M_TRUSTED 64 Indicates a SPAWN command on behalf of the application. If not set, captive accounts cannot spawn a subprocess

CLI_M_AUTHPRIV 128 The subprocess inherits the caller's authorized privileges.

CLI_M_SUBSYSTEM 256 The spawned process inherits protected subsystem IDs for the duration of the process creation.

CLI_M_NONRANDOM H100000000 A non-random process name prefix is used. See the name parameter for details.

name
A pointer to an SRB which points to the name to assign to the subprocess. If the specified name is already in use by another process, an error occurs and the subprocess is not created. If this parameter is 0, the name of the process will be the user name, an underscore, and a number. Normally a unique random number is used, but if the CLI_M_NONRANDOM flag is specified, the number will be "1", unless that process name is in use, in which case "2" is tried, and incremented by 1 until a unique process name is generated. For instance, if the user is "System", and there are already existing process names of "System_1", "System_2", and "System_4", then the new process will be named "System_3".

pid
A pointer to a 64-bit integer which receives the PID of the subprocess after it is created. If this parameter is 0, the process ID is not returned.

status
A pointer to a 64-bit integer which will receive the completion status of the subprocess. This is updated asynchronously if the the NOWAIT flag is used. If the subprocess completes without error, the result set to 0. If this parameter is 0, the completion status is not returned.

eventflag
A pointer to a 64-bit integer which contains the event flag to be set when the subprocess completes. If this parameter is 0, no event flag is set.

AST
A pointer to an AST to call when the subprocess completes. If this is 0, no AST routine is called. AST routines should be used if NOWAIT is specified in the flags and the calling process needs to know when the subprocess finishes.

ASTP
A pointer to a 64-bit integer containing the parameter value to pass to the AST routine. This is only meaningful if an AST address is provided.

prompt
A pointer to an SRB which points to the text to be used as a prompt in the shell of the subprocess. Depending upon the shell, this may have no effect.

shell
A pointer to an SRB which points to the name of the shell for the subprocess. If not specified, the default system shell is used.

reserved
This parameter reserved for future use. It is ignored, but 0 should be passed.

Description

This service creates a subprocess. The created subprocess inherits the following attributes from the calling process, although some of these can be modified by the passed flags:

Process symbols

Default device and directory

Process privileges

Process nondeductible quotas

The subprocess does not inherit process-permanent files nor execution or image context.
The set of authorized privileges in the subprocess is inherited from the caller's current privileges. If the calling image is installed with elevated privileges, these privileges are not available to the subprocess until a SETPRV call is performed in the subprocess to enable them. If the calling image is installed with elevated privileges, it should disable those privileges before the call to LIB_SPAWN unless the environment of the subprocess is strictly controlled. Otherwise, elevated privileges may accidentally be made available to the user.
If neither command nor input is specified, command input is taken from the parent process' terminal. If both command and input are specified, the subprocess first executes command and then reads from input. If only command is specified, the program is executed, and the subprocess is terminated when the program exits. If input is specified, the subprocess is terminated by either a LOGOUT procedure or an end-of-file.
The LOGIN utility is not run and no LOGIN.COM file is executed.
Unless the NOWAIT flags bit is set, the caller's process is put into hibernation until the subprocess finishes. Because the caller's process hibernates in supervisor mode, any user-mode ASTs queued for delivery to the caller are not delivered until the caller reawakes. Control can also be restored to the caller by a suitable call to LIB_ATTACH from the subprocess.

Condition Values Returned

SS_NORMAL Normal completion of service.
SS_DUPLNAM A process name was specified, but a process with that name is currently running.
INVARG A flag outside of the valid values was specified.
INVOPER Invalid operation.

In the next article, we will begin to look at the code to implement these services.