Version 4.2.6 for Mainframes
 —  Utilities  —

Special Considerations for Administrators

This section describes the security aspects of the SYSMAIN utility and the user exit routines supplied for SYSMAIN.


File Security

The file security (that is, passwords and cipher codes) relates to the security that has been defined for a system file in an Adabas or a VSAM environment. If file security has been defined for a system file, you need to specify a password, cipher code and/or VSAM name for the source and/or target system file required before you perform a SYSMAIN function. Otherwise, Adabas or VSAM will issue an appropriate error message. You do not have to provide security information for the default system files assigned to the Natural session at the start of the SYSMAIN utility.

Start of instruction set To specify passwords and cipher codes

  1. From any SYSMAIN utility menu, invoke a security window for the required system file by using either a PF key or a special command as indicated in the table below:

    System File Command PF Key Objects/Data Affected
    FUSER, FNAT SET FNAT PF12

    - programming objects
    - debug environments
    - error messages
    - profiles

    FDIC SET FDIC PF11

    - rules
    - DL/I subfiles
    - DDMs
    - XRef information

    FSEC SET FSEC PF10 - Natural Security profile

    The security window that appears for the specified system file looks similar to the example of the FUSER and FNAT system files below:

    +---------------------------------------------------+
    !   --- Security for the Natural System Files ---   !
    !                                                   !
    !  Specify the password(s), cipher(s) and VSAM FCT  !
    !  name(s) for the source/target file(s) below:     !
    !                                                   !
    !      - Source -                - Target -         !
    ! Library .... OLDLIB       Library .... NEWLIB     !
    ! Database ... 10           Database ... 10         !
    ! File ....... 32           File ....... 32         !
    !                                                   !
    ! Password ...              Password ...            !
    ! Cipher .....              Cipher .....            !
    ! VSAM Name .. ________     VSAM Name .. ________   !
    +---------------------------------------------------+
    
  2. In the window, enter the appropriate password(s), cipher code(s) and/or VSAM name for the required source and/or target system file.

    Note:
    The Library field is applicable only when processing programming objects, debug environments or error messages.

Once file security is defined, the SYSMAIN utility uses this security information for all subsequent processing. If you then require that the default security information (obtained at the initialization of the session) be used, you must re-invoke the corresponding security window and clear the password, cipher code and/or VSAM name fields. The passwords and cipher codes are non-display, so even though the fields appear to be empty, they should be cleared again.

Top of page

Natural Security

Two aspects must be considered when using the SYSMAIN utility within a Natural Security environment:

Defining the Natural Security Environment

The source and target libraries can be within one Natural Security environment or within two different Natural Security environments. These environments must be defined to the SYSMAIN utility.

The definition of the Natural Security environment(s) to be used is specified with the special command SET FSEC.

By default, the current FSEC settings assigned at the start of the Natural session are used. If you change these settings (in the window Security for Natural Security (FSEC) Files), they remain in effect until they are changed by the next SET FSEC process. In batch mode or direct command mode, the SEC keyword should be used to specify the file security and assignments of the request.

Once the source and target environments have been determined, SYSMAIN verifies both the source and target libraries with Natural Security. (The source and/or target database and file must correspond to the database ID (DBID) and file number (FNR) specified in the library security profile; if these values are not specified, default values are taken from the security profile.)

Restricting Use of SYSMAIN under Natural Security

The use of the SYSMAIN utility itself can be restricted, or the use of the source and target libraries to be handled with the SYSMAIN utility can be restricted. The use of SYSMAIN functions when invoked via the application programming interface MAINUSER can be controlled separately. See Protecting Utilities in the Natural Security documentation for details.

Top of page

User Exit Routines

The user exit routines of the SYSMAIN utility are used to provide information on each object being processed or control function processing. A user exit routine is a Natural subprogram, which is invoked with a CALLNAT statement.

The source codes of the subprograms and the data areas they use are stored as source objects under the names SM-UX-nn (nn = 01 to 11) in the library SYSMAIN. To make a user exit routine available, you have to catalog the corresponding source object under the name MAINEXnn, either in the library SYSMAIN or in one of its steplibs.

Note:
The names of source objects and cataloged objects of user exit routines are different to ensure that the overwriting of the source objects by an update installation does not affect the cataloged objects.

You can change or expand any of the user exit routines as necessary.

Use of these exits results in additional overhead to the SYSMAIN utility, depending on the code logic. It is necessary, however, always to return control to SYSMAIN when exit processing is completed.

As the SYSMAIN utility uses ET logic with Adabas files, the use of user exit routines can lengthen the transaction time limit (Adabas parameter TT). Furthermore, the definition of the Adabas transaction should not be altered, which means that you should not issue any ET/BT commands or END/BACKOUT TRANSACTION statements. SYSMAIN is responsible for the issuing of all END TRANSACTION statements. The exception to this rule is in a situation where a user terminates the normal completion of any SYSMAIN function with the user exit routines. If this is the case, you must issue a BACKOUT TRANSACTION before terminating.

If the return code is set to a non-zero value, this overrides any error given by SYSMAIN. When an error is received from an exit, it is placed in the message field and displayed or printed as appropriate. The exception is automated processing, because processing is completed with minimum terminal I/O.

The individual user exit routines are described in the following section:

MAINEX01 - First User Exit Routine for Object Interrogation

Function Interrogate the current value settings of the data elements associated with an object before the object is processed by SYSMAIN.
Remarks Any object passed to MAINEX01 can be rejected by setting the RESP-CODE parameter to a non-zero value.

If any additional logic is to be performed, the transaction may not be at end-of-transaction status and so no END TRANSACTION or BACKOUT TRANSACTION statement should be issued.

Control must be returned to SYSMAIN.

Parameters
PARM-AREA1 (A250) SYSMAIN parameter area (fixed values).
PARM-AREA2 (A250) SYSMAIN parameter area (variable values).
RESP-CODE (B1) Response code to be returned to SYSMAIN.

Note:
Only the RESP-CODE parameter can be modified.

Local Data Area SM-UX-L

MAINEX02 - Second User Exit Routine for Object Interrogation

Function Interrogate the current value settings of the data elements associated with an object after the object has been processed by SYSMAIN.
Remarks Any object passed to MAINEX02 can be rejected by setting the RESP-CODE parameter to a non-zero value.

If any additional logic is to be done, the transaction may not be at end-of-transaction status and so no END TRANSACTION or BACKOUT TRANSACTION statement should be issued.

Control must be returned to SYSMAIN.

Parameters
PARM-AREA1 (A250) SYSMAIN parameter area (fixed values).
PARM-AREA2 (A250) SYSMAIN parameter area (variable values).
RESP-CODE (B1) Response code to be returned to SYSMAIN.

Note:
Only the RESP-CODE parameter can be modified.

Local Data Area SM-UX-L

MAINEX03 - User Exit Routine for Request Interrogation

Function Interrogate any request made to SYSMAIN in terms of a direct command or information entered online in menu mode. MAINEX03 obtains control before SYSMAIN processes the command.
Remarks Any command passed to MAINEX03 can be rejected by setting the RESP-CODE parameter to a non-zero value.

Additional logic can be added, but it is your responsibility to issue any necessary END TRANSACTION requests to the database.

Control must be returned to SYSMAIN.

Parameters
PARM-AREA (A250) Command string.
RESP-CODE (B1) Response code to be returned to SYSMAIN.

Note:
Only the RESP-CODE parameter can be modified.

MAINEX04 - User Exit Routine for Modification of File Assignments

Function Override the database, file, password and cipher codes for the Natural system file(s).
Remarks MAINEX04 is invoked before any request is processed or validated by SYSMAIN. When control is passed to MAINEX04, you are at end-of-transaction status; therefore you have to set the RESP-CODE parameter to a non-zero value if you wish to reject the request.

Control must be returned to SYSMAIN.

Parameters
PARM-AREA (A250) SYSMAIN parameter area.
RESP-CODE (B1) Response code to be returned to SYSMAIN.
Local Data Area SM-UX-L4

MAINEX05 - User Exit Routine for Verification of Direct Commands

Function Verify any direct command entered during online processing of SYSMAIN. In addition, the special characters used to indicate a system command can be overwritten.
Remarks MAINEX05 is invoked before any direct command issued within SYSMAIN is processed. For example, MAINEX05 enables you to interrogate any of the SET commands (see Special Commands Issued to SYSMAIN) and also prevent them from being issued. You can verify these commands and reject them by returning a non-zero value in the RESP-CODE parameter. You are at end-of-transaction status when control is passed to MAINEX05.

A system command entered within SYSMAIN has to be preceded by two slashes (//); see also Using the SYSMAIN Command Line. With MAINEX05, you can define two other special characters for this purpose; to do so, you assign the desired characters to the CMD-DEL parameter. If CMD-DEL is set to blanks, SYSMAIN uses the default value of two slashes (//). Control must be returned to SYSMAIN.

Parameters
COMMAND (A68) Current command issued in SYSMAIN.
CMD-DEL (A3) Special character for system commands.
RESP-CODE (B1) Response code to be returned to SYSMAIN.

MAINEX06 - User Exit Routine for SYSMAIN Initialization

Function Obtain control at initialization of a SYSMAIN session.
Remarks MAINEX06 is invoked at the start of the SYSMAIN session, where you can override some of the SYSMAIN default settings, as for example, prompts for confirmation of a request like deleting, moving or replacing an object.

All parameters are verified. If they are invalid, the default settings are used.

Control must be returned to SYSMAIN.

Parameter
Data Area

SM-UX-L6

MAINEX07 - User Exit Routine for SYSMAIN Termination

Function Obtain control at termination of a SYSMAIN session.
Remarks MAINEX07 is invoked at termination of a SYSMAIN session to decide whether control is to be kept by SYSMAIN or not.
Parameters
USER-AREA (A50) Area for free usage.

MAINEX08 - User Exit Routine for Nothing Found in Batch Mode

Function Determine further processing if no objects are found for a command in batch mode.
Remarks MAINEX08 is invoked if no objects are found that meet the specified criteria for a specific command executed in batch mode. If this is the case, control may, but need not, be returned to SYSMAIN. If control is returned to SYSMAIN, SYSMAIN will continue processing with the next command.
Parameters
CMD (A250) Command string.

MAINEX09 - User Exit Routine for Abnormal Termination in Batch Mode

Function Determine action to be taken in case of error in batch mode.
Remarks MAINEX09 is invoked if SYSMAIN processing in batch mode leads to an error. If this is the case, control may, but need not, be returned to SYSMAIN. If control is returned to SYSMAIN, SYSMAIN will be terminated with condition code 45.

Note:
Errors NAT4810, NAT4818, NAT4867, NAT4868 and NAT4893 cannot be handled by this user exit routine.

Parameters
CMD (A250) Command string.
ERROR-CODE (N4) Number of error which caused termination.

MAINEX10 - User Exit Routine for Command Errors in Batch Mode

Function Determine action to be taken in case of command error in batch mode.
Remarks MAINEX10 is invoked if an error is detected in a SYSMAIN command in batch mode. If this is the case, control may, but need not, be returned to SYSMAIN. If control is returned to SYSMAIN, SYSMAIN will continue processing with the next command.
Parameters
CMD (A250) Command string.
ERROR-CODE (N4) Number of error which caused termination.

MAINEX11 - User Exit Routine for Setting Special Flags to SYSMAIN

Function Special settings user exit routine.
Remarks MAINEX11 is invoked at the start of the SYSMAIN session, where you can set some special SYSMAIN flags, as for example, display of MAINUSER messages in batch.

See the source object of the user exit routine (SM-UX-11) for the available flags.

Control must be returned to SYSMAIN.

Parameters
FLAGS (A250) Flag string (redefined).

Top of page