Authorized Services Manager under z/OS

#### Search Results

Search

# 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

- ASM System Requirements

- Starting the ASM

- ASM Operator Commands

- Resetting the Coupling Facility Structure for ASM

- ASM Messages, Condition Codes and Abend Codes

## 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,

- executing authorized system services for z/OS shared memory objects.

- executing authorized services using the RACROUTE interface of the z/OS Security Server (RACF or any other external security product)

The first three functions are always available, whereas the SIP is needed and used when Natural is running with SYSPLEX enabled. For more information about the parameters you must specify to keep session information records (SIRs) in the SIP, see the CICSPLX and SIPSERV parameters under Natural CICS Generation Parameters. The SIP which holds the SIRs in SIP slots 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. This is necessary if your systems programmer specified `VSM ALLOWUSERKEYCSA(NO)` in `SYS1.PARMLIB(DIAGxx`); 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 is required.

- Enablement of the Shared Memory Objects File Server (FSSM) of Natural for Db2 is required.

- Enablement of the ACEE caching (`SECURITY_CACHING=YES`) of the Natural Development Server.

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 Coupling Facility (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 for each Natural subsystem 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

- System Linkage Index

- CF Structure

- XCF Signaling Paths

### 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.

The size of a CF structure can be calculated using the IBM web utility "CFSizer", which can be found here:https://www.ibm.com/support/pages/cfsizer

There, you must choose "XCF" in the selection box, there where you see "Choose one".

You get a new window, which is pre-filled with "Number of systems" = 8 and "CLASSLEN" = 956 (= 936 + 20 -> CONA + CONALOCKATTR)

See macro `IXLYCONA` for those size:

    01 SIZE:
    *            CONA          -- X'03A8' bytes = 936
    *            CONALOCKATTR  -- X'0014' bytes =  20
    *            CONALISTATTR  -- X'0028' bytes =  40
    *            CONACACHEATTR -- X'001C' bytes =  28

Authorized Server needs CONA + CONALISTATTR = 936 + 40 = 976 bytes.

Once you select "Number of systems" = n (LPARs), and you press "Submit", you get something like (5 LPARs with 936 bytes):

Function | Type | Structure Name | INITSIZE | SIZE
--- | --- | --- | --- | ---
XCF | LIST | IXC...... | 18M | 19M

followed by a number of lines with JCL.

### 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`).

## 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. You can specify parameters in the JCL `EXEC` statement, in a parameter file, or in both. A parameter specified in the `EXEC` statement overwrites the corresponding parameter in the parameter file.

It is recommended that you use a parameter file (see Parameters in the Parameter File) because the parameters that control SIP timeout processing and future parameters can only be specified in the parameter file. Existing JCL will continue to execute unchanged.

This section covers the following topics:

- Parameters in the JCL EXEC Statement

- Parameters in the Parameter File

### Parameters in the JCL EXEC Statement

>   In 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,Update-ECSA-D

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

>   Parameter | Possible Values | Default Value | 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. An asterisk ("*") will produce the name "NAT" followed by the subsystem-name. It is, however, indicated that the name of a XCF group should always be specified.
>   `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. When `XCF-group-name` is specified while `CF-structure-name` remains empty, you will only be able to use the buffer pool propagation.
>   `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` or `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.
>   `Update-ECSA-D` | `ECSADUPD` or blank | blank | Update an older ECSA-Directory entry without the need for an IPL.

### Parameters in the Parameter File

The parameter file is a physical sequential file (`DSORG=PS`) that is allocated with `LRECL=80` and `RECFM=FB`. In your JCL, specify this file with `DDNAME ASMPARM`.

Parameters in the parameter file are specified as `name=value` pairs. Specify one parameter per line starting in Column 1. The `name=value` pair is terminated by the first blank, and the rest of the line is not examined. Lines starting with an asterisk (*) in Column 1 are treated as comments. Parameters are translated to upper case before they are processed.

Parameter | Possible Values | Default Value | Comment
--- | --- | --- | ---
`SUBSID=name` | 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.
`XCFGROUP=group-name` | any valid XCF group name | none | The name of the XCF group for Signaling services. An asterisk ("*") will produce the name "NAT" followed by the subsystem-name. It is, however, indicated that the name of a XCF group should always be specified.
`STRUCTURE=structure-name` | any valid CF structure name | none | Use only for the SIP function. The name of the CF structure used for the SIP function. When `XCFGROUP` is specified while `STRUCTURE` remains empty, you will only be able to use the buffer pool propagation.
`NUMSLOTS=number` | `1 - 2147483647` | none | Use only for the SIP function. 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.
`SLOTSIZE=size` | `256`, `512`, `1024`, `2048` or `4096` | `1024` | Use only for the SIP function. The specified value is ignored if a CF structure has already been allocated.
`MSGCASE=case` | `UPPER` or `MIXED` | `MIXED` | Specify `UPPER` if the Authorized Services Manager is to issue all its messages in upper case.
`NONACTIVITY=hours` | `1 - 999999` | none | Use only for the SIP function. The number of hours a SIP session can be inactive before it is deleted. If this time is exceeded, the session is deleted during the next scheduled timeout check. If this parameter is omitted, no timeout check will be executed. This parameter can be changed using the `TIMEOUT` operator command (see ASM Operator Commands). Both the Authorized Services Manager and the Roll Server allow to specify a timeout value. If Natural is running in a SYSPLEX environment, set the same value for this parameter and the `non-activity-time` parameter of the Roll Server.
`TIMEOUTCHECK=hhmm` | `0000 - 2359` | none | Use only for the SIP function. The time of day that the timeout check is to be run. Sessions will be deleted if they have been inactive longer than the non-activity time specified with `NONACTIVITY`. This parameter can be changed using the `TIMEOUT` operator command (see ASM Operator Commands).
`TIMEOUTREPEAT=mmmm` | `0 - 1440` | none | Use only for the SIP function. The number of minutes between two timeout checks. If `TIMEOUTCHECK` is also specified, the first check is run at the time specified with `TIMEOUTCHECK`, and then repeated after `mmmm` minutes. If `TIMEOUTCHECK` is not specified, the first check is run `mmmm` minutes after Authorized Services Manager start. This parameter can be changed using the `REPEAT` option of the `TIMEOUT` operator command (see ASM Operator Commands).
`FSSMDSTx` | See How to Enable Tracing for Dynamic SQL Statements in the Database Management System Interfaces documentation. | none | Parameters starting with `FSSMDSTx` are passed to NATFSSM, the Natural for Db2 part of the Authorized Services Manager (NATASM), to define a dynamic SQL trace buffer above the bar.
`FSSMxxxx` | See Defining Size and Format of an FSSM in the Database Management System Interfaces documentation. | none | Parameters starting with `FSSMxxxx` (`xxxx` must not be replaced with `DSTx`) are passed to NATFSSM, the Natural for Db2 part of the Authorized Services Manager (NATASM), to define the Natural for Db2 file server above the bar.
`ECSADUPD=option` | `no` or `yes` | no | Update an older ECSA-Directory entry without the need for an IPL.
`TIMEOUT=option` | `VERBOSE` or `TERSE` | `VERBOSE` | Displays or suppresses messages ASM0085 and ASM0086 during a `TIMEOUT` process.

> 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 EXEC PGM=NATASMvr,PARM='TST5'
>         //ASMPARM  DD DISP=SHR,DSN=FB.SYSF.PARMS(ASMPARM1)

>     File `FB.SYSF.PARMS(ASMPARM1)`:

>         MSGCASE=M              Mixed case messages
>         SUBSID=TST1
>         XCFGROUP=HELGA         Message group for global buffer pool administration
>         *SIP definitions:
>         STRUCTURE=TSTSIP       SIP CF structure
>         SLOTSIZE=256
>         NUMSLOTS=200
>         TIMEOUTCHECK=2135      Delete old sessions at 9:35 pm
>         NONACTIVITY=2          Delete sessions that have been inactive for 2 hours or more

>     The SIP service is to build 200 SIP slots in CF structure `TSTSIP`, each having a size of 256 bytes. The Natural subsystem to be used is `TST5`, as the parameter on the `EXEC` statement overwrites the `TST1` subsystem specified in the parameter file.

## ASM Operator Commands

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

Command | Description
--- | ---
`HELP` | Shows an overview of the available syntax.
`TERMinate` | `STOP` | Terminates the ASM.
`SNAP` | Debugging function. The ASM address space is dumped to `SYSUDUMP`.
`VLIST` | Displays the name, version and assembly time of modules that are linked to the ASM.
`TIMEOUT` | `NAT nnn` | Specifies or replaces the non-activity time parameter.
`REPEAT mmmm` | Specifies or replaces the time interval in minutes in which the timeout check is to be run.
`TOC hhmm` | Specifies or replaces the time of day of the timeout check.
`OFF` | Disables timeout checking.
`ON` | Reinstates timeout checking.
`NOW` | Starts an immediate timeout check. Normal timeout check scheduling (if specified) remains in effect.
`TERSE` | Suppresses the messages `ASM0078` and `ASM0080` during `TIMEOUT NOW` processing. Suppresses the messages ASM0085 and ASM0086 during a `TIMEOUT` processing. The message `ASM0047 Operator command: TIMEOUT NOW` is also suppressed.
`VERBOSE` | Displays the messages `ASM0078`, `ASM0080` and `ASM0047` during `TIMEOUT NOW` processing. Displays the messages ASM0085 and ASM0086 during a `TIMEOUT` processing. This is the default setting.
`?` (or no specification) | Displays the current timeout settings. The question mark (?) is optional and can be omitted.

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.

## Resetting the Coupling Facility Structure for ASM

When a CICS or IMS TM region which uses the Session Information Pool (SIP) function of the Authorized Services Manager abends, the Authorized Services Manager might return an error for the SIP. For example, the SIP might be reported as full because session cleanup had not been performed before the region abended. To resolve such an error, delete the respective Coupling Facility structure:

1. Shut down all Authorized Services Managers which use the affected CF structure.

2. Issue the operator command `SETXCF FORCE,STR,STRNAME=structure-name`, where `structure-name` is the name of the CF structure used for the SIP function.

3. Restart all Authorized Services Managers.

## 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 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
`4` | Authorised server not available
`8` | No space for work area
`12` | Wrong parameter input
`16` | Runtime error has occurred
`20` | Subtask has failed
`24` | Abend has occurred
`97` | Buffer pool routine not linked
`98` | Invalid buffer pool type
`99` | No more storage
>`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 support.
`U0104` | `IXCMSGI` failed. | Abend Register 14 contains the reason code.
`U0105` | Message Exit could not obtain a Purge Task Request Block. | Contact support.
`U0106` | Work Space for `IXLCONN` could not be obtained. | Contact support.
`U05xx` | `IXLCONN` failed. | xx is the reason code.
`U06xx` | `IXLLIST WRITE` failed. | xx is the reason code.
`U070x` | `STORAGE OBTAIN` for subpool 245 failed. | Contact support.
`U071x` | `STORAGE RELEASE` for subpool 245 failed. | Contact support.

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 support.

### On this page

- ASM Overview
- ASM System Requirements
- Starting the ASM
- ASM Operator Commands
- Resetting the Coupling Facility Structure for ASM
- ASM Messages, Condition Codes and Abend Codes