Authorized Services Manager under z/OS

This document describes functionality and operation of the Authorized Services Manager (ASM) which is available with Natural under z/OS.

This section covers the following topics:

ASM Overview

The Authorized Services Manager (ASM) provides authorized operating system functions to Natural. These functions include writing SMF records and z/OS Parallel Sysplex communication through the Coupling Facility (CF). The ASM provides its functions via PC routines and runs in its own address space.

The following authorized functions are provided:

  • communicating Natural buffer pool administration messages,

  • write-access to global buffer pools in system key,

  • writing SMF records,

  • holding Natural session information in the Session Information Pool (SIP),

  • executing authorized system services for IBM zIIP (System z Integrated Information Processor) support.

The first three functions are always available, whereas the SIP is optional and can be made available via startup parameter. For more information on starting the ASM, see Starting the ASM.

You must use the ASM in the following cases:

  • The Natural profile parameter BPPROP is set to PLEX or GLOBAL or GPLEX (buffer pool propagation is used).

  • Natural global buffer pools are allocated in system key; see also Allocation of the Natural GBP in the section Natural Global Buffer Pool under z/OS.

  • Natural under CICS is used in a z/OS Parallel Sysplex environment (SIP function required).

  • Natural under IMS TM is used in terminal-oriented, non-conversational mode (with the SIP function).

  • Natural under IMS TM is used, with the Accounting function writing SMF records.

  • Enablement of zIIP support.

The Session Information Pool (SIP) holds the Natural session information records. In terminal-oriented non-conversational mode, the Natural CICS Interface and the Natural IMS TM Interface need these records to continue a Natural session after a terminal I/O. When running in a z/OS Parallel Sysplex environment, the SIP is created in the CF and a memory object is used as an intermediate buffer to avoid unnecessary access to the CF. Otherwise, the SIP is created in a memory object. (A memory object resides in 64-bit-addressable storage above the 2-gigabyte address).

If the ASM is used in a z/OS Parallel Sysplex environment, one ASM instance must be started in each participating z/OS image.

Note concerning Natural/CICS: The CICS System Recovery Table should include the z/OS system abend code 0D6.

ASM System Requirements

This section describes the ASM system requirements.

APF Authorization

Link the modules NATASMvr (where vr represents the relevant product version) and NATBPMGR to an Authorized Program Facility (APF) library, specifying IEWL parameter AC(1). Refer to Installing Natural on z/OS.

System Linkage Index

As the ASM reserves one system linkage index (System LX), check whether there is a high enough value of NSYSLX in member IEASYSxx of library SYS1.PARMLIB.

Note:
If you terminate the ASM, the address space ID is no longer available because a System LX has been used. It becomes available again with the next IPL.

CF Structure

A CF structure is used if you run the SIP in a z/OS Parallel Sysplex environment.

XCF Signaling Paths

The XCF Signaling Services are used to propagate buffer pool administration messages in a z/OS Parallel Sysplex environment. The minimum message is 64 bytes long, the maximum is 2048 bytes. How often messages are sent depends on how often Natural objects are manipulated (with the system command CATALOG, STOW or DELETE).

ASM Operation

The following is covered below:

Starting the ASM

You start the ASM either as a batch job or as a started task by executing module NATASMvr, where vr represents the relevant product version. On the JCL EXEC statement, specify as PARM the following parameters: 

subsystem-id,XCF-group-name,CF-structure-name,number-of-SIP-slots,SIP-slot-size,message-case

All parameters are positional and must be separated by a comma; they are explained in the table below:

Parameter Possible Values Default Comment
subsystem-id 4-byte non-blank string NATv

The specified value must match the value of the Natural profile parameter SUBSID (v is version).

Note:
With Natural under CICS, refer to the CICSPLX parameter in the NCMDIR macro for setting the appropriate subsystem ID.

XCF-group-name any valid XCF group name none The name of the XCF group for Signaling services.
CF-structure-name any valid CF structure name none Optional, only needed if SIP is used. The name of the CF structure used for the SIP function.
number-of-SIP-slots 1 - 2147483647 none Optional, only needed if SIP is used. The number of slots to be allocated if the CF structure has not yet been allocated. If omitted or specified as 0, the entire structure will be used for as many slots as it can hold.
SIP-slot-size 256, 512, 1024, 2048, 4096 1024 The specified value is ignored if a CF structure has already been allocated.
message-case UCTRAN or blank blank Specify UCTRAN if the Authorized Services Manager is to issue all its messages in upper case.

Examples:

In the following examples, v or vr represents the relevant one- or two-digit product version

//ASM EXEC PGM=NATASMvr,PARM='NATv,NATXCF,CFSIP,1500,512'

The subsystem ID is NATv, the message group for buffer pool communication is NATXCF, the structure for the Session Information Pool is CFSIP. 1500 SIP slots are to be used, each having a size of 512 bytes. 

//ASM EXEC PGM=NATASMvr,PARM='NATv,NATXCF,CFSIP'

Same as above, except SIP slots:

The ASM will use as many SIP slots as the CFSIP structure can hold, each having a size of 1024 bytes. 

//ASM EXEC PGM=NATASMvr,PARM='NATv,NATXCF,,500,512'

The SIP service is not to use the Coupling Facility, but to build 500 SIP slots in storage, each having a size of 512 bytes. 

//ASM EXEC PGM=NATASMvr,PARM='NATv,NATXCF'

The SIP service will not be available.

ASM Messages, Condition Codes and Abend Codes

The ASM writes informational and error messages to JESMSGLG using the WTO macro (ROUTCDE=11). The messages are preceded by a message identifier and the ASM's job name, for example: 

ASM0005 FBASMvr

In this example, Authorized Services Manager Version vr (where vr represents the relevant product version) is active

The following condition codes are used:

Condition Code Explanation
0 Normal completion
12 Wrong parameter input
16 Runtime error has occurred
20 Subtask has failed
24 Abend has occurred
>100 Working storage could not be allocated

The following user abend codes are used:

Abend Code Reason Comment
U0100 IXCJOIN failed. Abend Register 14 contains the reason code.
U0101 IXCQUERY failed. Abend Register 14 contains the reason code.
U0103 Active member list full. Contact Software AG Support.
U0104 IXCMSGI failed. Abend Register 14 contains the reason code.
U0105 Message Exit could not obtain a Purge Task Request Block. Contact Software AG Support.
U0106 Work Space for IXLCONN could not be obtained. Contact Software AG Support.
U02xx DSPSERV CREATE failed. xx is the reason code.
U03xx ALESERV ADD failed. xx is the reason code.
U04xx ALESERV ADD failed. xx is the reason code.
U05xx IXLCONN failed. xx is the reason code.
U06xx IXLLIST WRITE failed. xx is the reason code.

To find a description of reason codes, refer to Programming: Sysplex Services Reference (IBM documentation). If the error was environment-specific, and it is not clear what the reason was, contact Software AG Support.

ASM Operator Commands

The following commands can be passed to the ASM using the MODIFY command:

Command Description
TERM Terminates the ASM.
SNAP Debugging function. The ASM's address space is dumped to SYSUDUMP.
VLIST Display name, version, and assembly time of modules that are linked to the ASM.

For a list of return codes and reason codes of the SIP Service, refer to SIP Service Return Codes and Reason Codes in the Messages and Codes documentation.