Configure the z/OS data set and file REST services

To use the z/OS data set and file REST services, you must configure it as described in this topic.

Dependencies on other z/OSMF services

None.

Security setup

To assist you with performing the security setup, IBM provides the sample security job IZURFSEC in SYS1.SAMPLIB.

Do the following:
  1. Make a copy of this job.
  2. Review and edit the job, if necessary.
  3. Submit the job as a batch job on your z/OS system.

Ensure that the IZURFSEC job completes with return code 0000. To verify, check the results of the job execution in the job log, for example, by using SDSF.

Host system customization

Host system customization consists of the following tasks:

Ensure that CEA is active in full-function mode

The z/OS common event adapter (CEA) service must be configured and started in full-function mode to run this service, as described in Ensure that common event adapter (CEA) is configured and active.

Logon procedure for the z/OSMF REST interfaces

IBM supplies a default logon procedure, IZUFPROC, in the PROCLIB data set. The procedure is used internally by the z/OSMF REST interfaces. Review the procedure to ensure that it is suitable for use in your environment.

Ensure that the SMP/E-managed PROCLIB data set resides in the JES PROCLIB concatenation that is used for TSO/E logon procedures. Or, copy IZUFPROC to a data set that is in the JES PROCLIB concatenation. For more information, see z/OS TSO/E Customization.

Note: z/OSMF uses the ISPEXEC load module in the ISPF library SISPLOAD. If your installation does not include the SISPLOAD data set in the link list, you must add SISPLOAD to the ISPLLIB DD concatenation in the logon procedure.
If you prefer, you can use a different logon procedure, if it provides the same function as the shipped IZUFPROC procedure. Specifically, the logon procedure must contain, at a minimum:
  • All of the DD statements from IZUFPROC; these must reference the system data sets that contain the z/OS UNIX REXX exec programs and ISPF libraries.
  • The PROC statement must specify the z/OSMF root code directory path on the ROOT variable, for example: ROOT='/usr/lpp/zosmf'

    If your installation configured z/OSMF to use another path for the root code directory, specify that path instead. The path must be enclosed in quotation marks, begin with a forward slash ('/'), and be fully qualified (it cannot be relative). Mixed-case file system names are allowed.

  • If your installation uses permanent (non-temporary) data set for ISPFPROF, the logon procedure must be configured to allow profile sharing.
  • The PROC statement must specify the Language Environment message file (MSGFILE), which is used for storing runtime messages from the z/OS data set and file REST services. For details, see Output messages file.

The topic IZUPRMxx reference information describes options for the TSO/E logon procedure that can be specified on the COMMON_TSO statement. You can specify a different TSO/E logon procedure name, account number, and address space region size, or use the default specifications.

The defaults should be adequate for most z/OS installations. If you specify alternative values, you must ensure that the z/OSMF user and z/OSMF administrator security groups are authorized to use the logon procedure name and account number that you specify. Also, ensure that the address space region size is at least 50 MB, and that your SMFLIMxx parmlib member and IEFUSI exit allow TSO/E users to use this amount of memory.

All z/OSMF users must have TSO segments that are defined in your installation's security database. Failure to have a TSO segment causes some z/OSMF functions not to work.

Output messages file

The z/OS data set and file REST services write runtime messages to a common output messages file. The messages describe error conditions and suggest possible solutions to the errors. By default, these messages are written to SYSOUT.

Your installation can select another destination for message output by using the Language Environment MSGFILE runtime option. In the logon procedure that is used by the z/OS data set and file REST services, ensure that the message file ddname is specified, as follows:
  • If your installation does not specify a message file ddname, you must ensure that the SYSOUT DD statement is specified in the logon procedure. For example: 
    //SYSOUT   DD SYSOUT=H
  • If your installation uses the Language Environment MSGFILE runtime option, you must ensure that the logon procedure is changed accordingly.
    To view the current MSGFILE definition on your system, you can use the following command: 
    D CEE,ALL
    Which displays output, such as the following: 
    PARMLIB(CEEPRM60)               MSGFILE(LEMSG,FBA,121,0,NOENQ)
    In this example, the message file ddname is LEMSG (not SYSOUT). Thus, you would modify the logon procedure, as follows: 
    //LEMSG   DD SYSOUT=H
    Or, to write the data to a specific data set, you can modify the logon procedure, as follows: 
    //LEMSG DD DSN=YOUR.CREATED.DATASET,DISP=OLD

    In this example, the diagnostic logs are written to the data set that you specify. Ensure that the data set is created with the format FBA,121,0,NOENQ.

Reviewing the IPCMSGQBYTES option of BPXPRMxx

The z/OS data set and file REST interface uses the z/OS UNIX System Services interprocess communications (IPC) message queue for communications between TSO/E and z/OSMF. The maximum message size is controlled by the size of the queue that is defined by the IPCMSGQBYTES option of parmlib member BPXPRMxx.

It is required that you specify an IPCMSGQBYTES value of at least 20971520 (20 M) in BPXPRMxx. To set this value dynamically, you can enter the following operator command: 
SETOMVS IPCMSGQBYTES=20971520

Optional extensions to this service

None.