In the following sections, each system service description contains the following information:
• Syntax This section describes the format for coding a macroinstruction. The programmer must adhere to assembly language syntax rules as described in the VS Assembly Language Reference when coding the macroinstructions. Parameters for the call are listed in the reverse order in which they are pushed onto the parameter block. That is, the return code address is always the last parameter pushed. As the macro generates the code to push the parameters in the expected order, assembly language programmers may code the call to the service with the parameters in any order. However, high-level language programmers must respect the order shown in the syntax section of the system service description.
• Function -- This section describes the functions of the service.
• Parameter definitions -- This section describes in detail the parameters that may be used with the macro call, and their valid values. Unless otherwise stated, the argument to a KEYWORD is the address of the value, not the value itself. The address may be a register specification in parenthesis or an address expression. This section also describes whether the parameter is an input or output parameter and the parameter's data type.
•
Return Codes -- This section lists the valid return codes for the system service. A return code of zero always indicates success.The SYSERROR macro in Chapter 4 is provided for standardization of user program error message. The return code section is omitted for macroinstructions that generate or describe system data structures.
• Example -- The section contains at least one coding example for each macro. Also included is the code generated when the macro is expanded and the static sections statements containing constant or storage declarations for the parameters.
Data Types
The data type descriptions are represented in PL/1 notation for easy interpretation by high-level language progranuners. Table 3-1 is a conversion chart from PL/1 to assembly language.
.~
a
Table 3-1.
PL/l
Fixed bin(31,0) Fixed bin(15,0) Char(n)
Char(n) vara Bit(n)
Pointer
Data Type Conversion Table Assembler
DS F DS H DS CLn DC H'n' DS CLn DS BL.n DS A(symbol)
The char(n) var data type assumes that the first two bytes (halfword aligned) contain a count of the number of characters that follow. The variable n specifies the maximum number of characters that may follow.
Error Handling Routines
Some of the services have an additional optional parameter for specifying the entry point of an error handling routine. The syntax is:
[ ,ERROREXIT=label]. When a service returns a code indicating a failure in the call and the ERROREXIT parameter is specified, the system transfers control to the address specified with the ERROREXIT parameter.
3.2.1 CNTROLOG - Control Logging of System Security Events Syntax
[label] CNTROLOG RC=returncode
Function
[,SETEVENTS=setevents]
[,RESETEVENTS=resetevents]
[,SETVIOLATION=setviolation]
[,RESETVIOLATION=resetviolation]
[,CONTROL=control [,NEWLIB=newlibrary]
[,NEWVOL=newvolume]
[,GETEVENTS=getevents]
[,GETVIOLATIONS=getviolations]
[,GETSTATUS=getstatus]
[,ACTFILE=activefile]
[,ACTLIB=activelibrary]
[,ACTVOL=activevolume]
[,INACTFILE=inactivefile]
[,INACTLIB=inactivelibrary]
[,INACTVOL=inactivevolume]
[,SETALTVOL=setalternatevolume]
[,SETNRECS=setnrecs]
[,GETALTVOL=getalternatevolume]
[,GETNRECS=getnrecs]
CNTROLOG communicates control information to the operating system security logging task. This service provides the following functions:
1. Start and stop logging up to 256 individual types of events.
2. Start and stop logging of attempted violations of up to 256 individual events.
3. Specify a new file name to be used for logging events or continuing using an already active file.
4. Return the types of events which are currently being logged, the types of events whose attempted violations are being logged, the status of the logging task, the volume, library and file of the active logging file, the volume, library and file of the inactive logging file.
Events consist of logon, logoff, file open and close, file rename,
.
file delete, file attribute change, userlist change, program invocation, procedure invocation, background job initiation, DP print request, WP print request, mount and dismount commands, operator-user conununications, system messages to the operator, attach/detach of disks and printers, acquire/release of workstations, system snapshot dumps, and attempted violations. See the LOGR macro for the event/bit definitions.
When starting the logging task with the new log file option, the system creates a file name that consists of the time and date of file creation. The caller specifies the library and volume with the NEWLIB and NEWVOL parameters. To obtain the file specification for a log file just closed as a result of a new log file request, specify the INACTFILE, INACTLIB and INACTVOL output parameters on the same call to CNTROLOG as the request to start a new log file. The system returns the file specification of the new file in the ACTFILE, ACTLIB and ACTVOL parameters.
The caller must have system administrator and operator privileges to perform the privileged functions of this service.
Parameter Definitions Parameter
Definition activefile
I/O
Output
Data TyPe
char(8) var
Returns the name of the currently active log file. If used when opening a new log file (CONTROL=2), CNTROLOG returns the name of the newly created log file.
activelibrary Output char(8) var
Returns the name of the library of the currently active log file. If used when opening a new log file CCONTROL=2) , CNTROLOG returns the library of the newly created log file.
activevolume Output char(8) var
Returns the name of the volwne of the currently active log file. If used when opening a new log file CCONTROL=2), CNTROLOG returns the volume of the newly created log file.
control Input fixed bin(31,0)
Changes the state of the logging facility. A value of 3 means that ~, logging is restarted, and is to continue using the same log file that
was used the last time logging was active. If logging is already active, this is an invalid request, and the caller is notified. A value of 1 causes logging activity to terminate (the caller is notified if logging is not active). A value of 2 causes a new log file to be opened. If logging is active at the time of the call, then the current file is closed. If logging is inactive, then logging is started. Parameter restricted to privileged callers.
getalternatevolwne Output char( 6 )var
Returns the name of the volwne to be used if the primary volwne cannot be used. Cannot be used with SETALTVOL.
get events Output bit(256)
Returns the events which are being logged. Each bit represents an individual event. This parameter may not be used with the SETEVENTS or RESETEVENTS parameters.
getnrecs Output fixed bin(31,0)
Returns the value set by the last SETNRECS. This is the number used to set the initial extent size when opening a new log file.
It cannot be used with SETNRECS.
getstatus Output fixed bin(31,0)
Returns the state of the logging facility. A value of 0 means that logging is inactive. A value of 1 means that logging is active.
This parameter may not be used with the CONTROL parameter.
getviolations Output bit(256)
Returns the events whose attempted violations are being logged.
Each bit represents an individual event. This parameter may not be used with the SETVIOLATIONS or RESETVIOLATIONS parameters.
inactivef ile Output char(8) var
Returns the name of the log file just closed by the CONTROL=2 action. This parameter may only be used in conjunction when specifying CONTROL=2. Restricted to privileged callers.
inactivelibrary Output char(8) var
Returns the name of the library of the log file just closed by the CONTROL=2 action. This parameter may only be used when specifying CONTROL=2. Restricted to privileged callers.
inactivevolume Output char(8) var
Returns the name of the volume of the log file just closed by the CONTROL=2 action. This parameter may only be used when specifying CONTROL=2. Restricted to privileged callers.
newlibrary Input char(8) var
The name of the library in which the new log file is to be created. This parameter is only valid when specifying CONTROL=2.
Restricted to privileged callers. Defaults to last library used.
newvolume Input char(8) var
The name of the volume on which the new log file is to be created.
This parameter is only valid when specifying CONTROL=2. Restricted to privileged callers. Defaults to last volume used.
resetevents Input bit(256)
Determines the events which are no longer to be logged. Each bit represents an individual event. Bi ts set to 1 wi 11 correspond to events to be turned off (not to be logged). If both SETEVENTS and RESETEVENTS are specified at the same time, RESETEVENTS will be processed first. Restricted to privileged callers.
resetviolations Input bit(256)
Determines the events whose attempted violations shall no longer be logged. Each bit represents an individual event. Bits set to 1 will correspond to events to be turned off (not to be logged). If both SETVIOLATIONS and RESETVIOLATIONS are specified at the same time, RESETVIOLATIONS will be processed first. Restricted to privileged callers.
returncode Output fixed bin( 31, 0)
Code indicating the success or failure of the routine call.
setalternatevolume Input char(6) var
The name of a volume to be used as an alternate volume when the primary volume cannot be used. Defaults to NEWVOL if no previous ALTVOL specified. Restricted to privileged callers.
set events Input bit(256)
Determines the events to be logged. Each bit represents an ~.
individual event. Bits set to 1 indicate the events to be logged.
Restricted to privileged callers.
setnrecs Input fixed bin(31,0)
The size of the initial extent of a new log file records) . This number is used to get UFBNRECS.
privileged callers.
C in number of Restricted to setviolations Input bit(256)
Determines the events whose attempted violations are to be logged.
Each bit represents an individual event. Bits set to 1 will correspond to events to be logged. Restricted to privileged callers.
Return Codes Code
@ERACC
@ERGETRSTEVENTS
@ERGETRSTVIOLS
@ERGETSETEVENTS
@ERGETSETVIOLS
@ERINACTNOTNEW
@ERIOERR
@ERIPTYP
@ERLOGGINGON
@ERLOGINACTIVE
Definition Access denied.
Cannot do both getevents and resetevents on same CNTROLOG call.
Cannot do both getviolations resetviolations on same CNTROLOG call.
and Cannot do both getevents and setevents on same CNTROLOG call.
Cannot do both getviolations and setviolations on same CNTROLOG call.
Cannot request inactivefile when not doing a newlog on CNTROLOG call.
I/O error.
Illegal parameter type.
Logging is already active.
Logging is not active.
.~
I~
Cannot do both getalternatevolume and setalternatevolume on same CNTROLOG call.
Cannot do both getnrecs and setnrecs on same
+#CNTROLG STATIC
+ ORG #CNTROLG + DC V(CNTROLOG)
+ CSECT
+ L
+ L
+ PUSH
+ LA
+ JSI
+ POPN
l,=R(#CNTROLG) l,O(R14,l) 0,1
l,4(,15) 0(,15) 0,60
(Static Section) RCODE OS F
EVENTMAP DC BL.256'0' VIOMAP DC BL.256'0' LOGFILE DC CL8' LOGLIB DC CL8' LOGVOL DC CL6' ONOFF DC F'O'
. Section for PUTLOG VCON . . Start the section . . . .
• . . . with the VCON •
• Rejoin current section •
• Address Static Section •
• Add Static Base . . Enstack VCON Address . . Address Parameters .
• Call PUTLOG .
• Restore Stack .
3.2.2 LOGR - System Security Logging Record Format Syntax
[label] LOGR [NODSECT][,STORAGE={ NO}]
{YES}
Function
This macro generates a DSECT which defines all the fields found in a security logging system PUTLOG record, their identifiers, •and the event types and subtypes. I t optionally allocates storage for a code section through the NODSECT parameter. The STORAGE parameter controls the amount of storage allocated for a code section (if NODSECT is specified) or the off sets shown in a DSECT. Also may be used in conjunction with the CNTROLOG macro for setting events.
Parameter Definitions Parameter
Definition NODSECT
I/O
Input
Data Type
Specifying NODSECT results in storage being allocated as part of the current code or static section. If not specified, the system generates a dwmny section (with no storage allocation) showing offsets relative to the beginning of the section.
STORAGE Input
STORAGE=YES sets the replication factor for each DS statement to one starting with LOGR$TYPE. STORAGE=NO sets the replication factor for each DS statement to zero. If NODSECT is specified, specifying STORAGE=YES generates storage for the total macro. Specifying NODSECT, STORAGE=NO generates storage for the shorter form of the macro.
Example
+LOGRFIELDVALUE DS OXL256 +LOGRHDR DS OX +LOGR#VIOLATION EQU 252 +LOGR$VIOLATION DS OBL2 +LOGR@ALERT EQU 1
Contains the field identifier.
Contains the length of the field
+LOGR$SWS
+LOGR$LOGONERR DS OXLl +LOGR@INVIDPSW EQU 1
+*****************************************
+* Opens for Input Only * +*****************************************
+ ORG LOGREVENTDATA
+LOGROPENINPUT EQU 3 Opens for input only event type +LOGR#OICLASS EQU 1 File class of file opened
+LOGR$0ICLASS DS OCL8
+LOGR#OIDEVCLASS EQU 2 Device class (from UCBCLASS) +LOGR$0IDEVCLASS DS OXLl
+LOGR#OIDEVICE EQU 3 Device name +LOGR$0IDEVICE DS OCL8
+LOGR#OIOWNER EQU 4 User ID of file owner +LOGR$0IOWNER DS OCL8
+LOGR#OIFILE EQU 5 File name of file opened +LOGR$0IFILE DS OCL8
+LOGR#OILIB EQU 6 Library of file opened +LOGR$0ILIB DS OCL8
+LOGR#OIVOL EQU 7 Volume of file opened +LOGR$0IVOL DS OCL8
+LOGR#OITYPE EQU 8 Open type (from UFBF2) +LOGR$0ITYPE DS OXLl
+LOGR#OIERROR EQU 9 Error on protection violation +LOGR$0IERROR DS OXLl
+*****************************************
+* Opens for Possible Modification * +*****************************************
+ ORG LOGREVENTDATA
+LOGROPENMOD EQU 4 Opens for possible modification event type +LOGR#OMCLASS EQU 1 File class of file opened
+LOGR$0MCLASS DS OCL8
+LOGR#OMDEVCLASS EQU 2 Device class (from UCBCLASS) +LOOR$0MDEVCLASS DS OXLl
+LOGR#OMDEVICE EQU 3 Device name +LOGR$0MDEVICE DS OCL8
+LOGR#OMOWNER EQU 4 Userid of file owner +LOGR$0MOWNER DS OCL8
+LOGR#OMFILE EQU 5 Filename of file opened +LOGR$0MFILE DS OCLB
+LOGR#OMLIB EQU 6 Library of file opened +LOGR$0MLIB DS OCL8
+LOGR#OMVOL EQU 7 Volume of file Opened +LOGR$0MVOL DS OCL8
+LOGR#OMTYPE EQU 8 Open type (from UFBF2) +LOOR$0MTYPE DS OXLl
+LOOR#OMERROR EQU 9 Error on protection violation +LOGR$0MERROR DS OXLl
.~
+************************************** +LOGR$SUADN1\ME DS OCL24
+* ***************************************************
+* There are still more subtypes to define here.
Security subtype for change program access rights
Program invocations event type File class of program
Procedure invocations event type File class of procedure
Userid of owner of file File name of procedure Library of procedure Volume of procedure
+••···
+* Background Jobs * Library of procedure Volume of procedure Job name used+* ***************************************************
+* * Subtype Submit for Background Jobs Event Type * +• ***************************************************
+LOGRSUBBGSUB EQU 1 Subtype submit background job +LOGR#BGSCLASS EQU 5 File class of procedure
+LOGR$BGSCLASS DS OCL8
+LOGR#BGSOWNER EQU 6 User ID of file owner +LOGR$BGSOWNER DS OCL8
+LOGR#BGSJOBCLAS EQU 7 Job class +LOGR$BGSJOBCLAS DS OCLl
+LOGR#BGSJOBTYPE EQU 8 Type of job +LOGR$BGSJOBTYPE DS OXLl
+LOGR@BGSPERM EQU X'80' . Permanent Job
+• •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
+* * Subtype Job Initiation for Background Jobs Event Type * +• ***********************************************************
+ ORG LOGREVENTDATA
+LOGRSUBBGJINIT EQU 2 Subtype job initiation +* There are no additional fields for this subtype
+• ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
+* • Subtype Job Termination for Background Jobs Event Type
*
+* ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
+ ORG LOGREVENTDATA +LOGRSUBBGJTERM EQU 3
+LOGR#BGJTWHY EQU 9
Subtype job termination Reason for job termination
. Normal completion
. Error completion (cancel program exception, etc.) . Expired time limit
. Cancelled by operator
condition,
+**************************************
+* DP Print Jobs *
+**************************************
+ ORG LOGREVENTDATA
+LOGRDPPRINT EQU 13 DP print jobs event type +* Fields common to all subtypes within the print jobs +* event type.
+LOGR#DPSFILE EQU 1 File name of print file +LOGR$DPSFILE DS OCLB
+LOGR#DPSLIB EQU 2 Library of print file +LOGR$DPSLIB DS OCLB
+LOGR#DPSVOL EQU 3 Volume of print file +LOGR$DPSVOL DS OCLB
+* ***************************************************
+* * Subtype Submit for DP Print Jobs Event Type * +* ***************************************************
+LOGRSUBDPSUB EQU 1 Subtype submit DP print job +LOGR#DPSCLASS EQU 5 File class of print file +LOGR$DPSCLASS DS OCLS
+LOGR#DPSOWNER EQU 6 User ID of file owner +LOGR$DPSOWNER DS OCLS
+LOGR#DPSPRTCLAS EQU 7 Print class +LOGR$DPSPRTCLAS DS OCLl
+* ***********************************************************
+* * Subtype Job Initiation for DP Print Jobs Event Type * +* ***********************************************************
+ ORG LOGREVENTDATA +LOGRSUBDPJINIT EQU 2
+LOGR#DPJIPRTR EQU 8 +LOGR$DPJIPRTR DS OCLS
Subtype job initiation Name of printer used
+* ************************************************************
+* * Subtype Job Termination for DP Print Jobs Event Type * +* ************************************************************
+ ORG LOGREVENTDATA +LOGRSUBDPJTERM EQU 3
+LOGR#DPJTWHY EQU 10 +LOGR$DPJTWHY DS OXLl +LOGR@DPJTNORM EQU 1 +LOGR@DPJTREAD EQU 2 +LOGR@DPJTPRTR EQU 3 +LOGR@DPJTOPER EQU 4
Subtype job termination Reason for job termination
. Normal completion
. I/O errors reading input file . I/O errors on printer
. Cancelled by operator
+******~*******************************
Operator-user communications event type Sender of message
+LOGR@OUOPTONE EQU 1 • Send to single user +LOGR$0UMESSAGE DS OCL160
+************************************** +LOGR$SOMESSAGE DS OCL160
System messages to operator event type
Attach/detach devices event type Attach or detach
Acquire/release devices event type Acquire or Release
+**************************************
System snapshots event type User ID of operator
Logging started because of Newlog command Logging started because of Continue command
Logging stopped because Stop command issued
Logging stopped because Newlog command issued
+**************************************
+* Operator message to Logging Task * +**************************************
+ ORG LOGREVENTDATA +LOGROPRMSG
+*
EQU 23 Operator message to logging task event Type
User ID of operator +LOGR#OMUSER
+LOGR$0MUSER +LOGR#OMOPRDEV +LOGR$0MOPRDEV +LOGR#OMMESSAGE +LOGR$0MMESSAGE
+ ORG ,
+LOGRLENGTH
EQU 1 DS OCLS
EQU 2 Name of device used as operator OS OCLS
EQU 3 The text of the message sent
+
OS OCL160
EQU *-LOGRBEGIN CSECT
END BEGIN
3.2.3 MSMAP - Map Region of Virtual Address Space Syntax
[label] MSMAP
Function
RETURNCODE=returncode, PATHNAME=pathname, TYPE=type,
OPTION=option,]
COMMAND=conunand, [,READLEVEL=readlevel]
(,WRITELEVEL=writelevel]
,STRTADDR=strtaddr [,LOWERVA=lowerva,]
[ UPPERVA=upperva]
[,FILESIZE=filesize]
[,FILECLS=fileclass]
MSMAP provides for mapping program and data files into a task's virtual address space. The file may already exist or may be opened in exclusive or shared mode when issuing the MSMAP call. Through the COMMAND parameter, the user may specify mapping at a specific address, within a range of addresses or at any available address. The recommended choice is at any available address. MSMAP returns the mapped address through the STRTADDR parameter. Files must be aligned on a 1/8-MB boundary.
The caller may also specify the process level required to read or write to the file. For all nonprivileged code, the read and write levels default to process level 0.
Parameter Definitions Parameter
Definition command
I/O
Input
Data Type
fixed bin(l5,0)
Specifies the address at which the file is to be mapped. The values may be 0, 1, or 2. A value of 0 means to map the file at any available location and is the recommended choice. A value of 1 means to map at any available location between the addresses specified by the LOWERVA and UPPERVA parameters. A value of 2 means to map at the address specified by the STRTADDR parameter. In all three cases, the file must be aligned on a 1/8-MB boundary. If COMMAND=2, this means that STRTADDR must specify an address which is an integer multiple of 1/8-MB. If COMMAND=l, then the range specified by LOWERVA and UPPERVA must contain at least one 1/8-MB boundary.
fileclass Input char( 1)
file security access code of the data file to '#' or 'A' or '). If FILECLS is not output file class of the caller is used for This parameter is only used when creating a FILECLS specifies the
be mapped (such as specified, the default the mapped data file.
data file.
filesize Input fixed bin(31,0)
FILESIZE specifies the initial size (in bytes) of the file. This parameter is required only when creating a new data file.
lowerva Input pointer
Specifies the lower virtual address limit at which the file may be mapped. Required only if specifying a range of addresses for the map (COMMAND=!). UPPERVA must also be supplied.
option Input fixed bin(15,0)
OPTION specifies that the data file already exists or is to be created. This parameter is required only if mapping an exclusive data file (TYPE=2) or a shared data file (TYPE=3). A value of O
means to map an existing data file with a specified name. A value of 2 means to create and map a data file with a specified name and file size.
pathname Input charC22) varying
PATHNAME specifies the volume, library, and file name of the file to be mapped. The parameter must be generated as follows: a
PATHNAME specifies the volume, library, and file name of the file to be mapped. The parameter must be generated as follows: a