Processing in sample connection and sign-on routines

Recommendation: Consider using the sample routines as a starting point when you write your own routines.

Both the sample connection routine (DSN3SATH) and the sample sign-on routine have similar sections for setup, constants, and storage areas. Both routines set values of the primary ID, the SQL ID, and the secondary IDs in three numbered sections.

In the sample connection routine (DSN3SATH): The three sections of the sample connection routine perform the following functions:

Section 1

Section 1 provides the same function as in the default connection routine. It determines whether the first character of the input primary ID has a value that is greater than blank (hex 40), and performs the following operations:

• If the first character is greater than hex 40, the value is not changed.
• If the first character is not greater than hex 40, the value is set according to the following rules:
  • If the request is from a TSO foreground address space, the primary ID is set to the logon ID.
  • If the request is not from a TSO foreground address space, the primary ID is set to the job user ID from the JES job control table.
  • If no primary ID is located, Section 2 is bypassed.

Section 2

At the beginning of Section 2, you can restore one commented-out instruction, which then truncates the primary authorization ID to 7 characters. (The instruction is identified by comments in the code.)

Section 2 next tests RACF® options and makes the following changes in the list of secondary IDs, which is initially blank:

• If RACF is not active, the list remains blank.
• If the list of groups option is not active, but an ACEE exists, the connected group name is copied as the only secondary ID. The source of the ACEE is one of the following:
  • An ACEE that is passed by the caller
  • The address-space-level ACEE
  • The task-level ACEE if the connection is for batch utilities.
• If the list of groups option is active, the list of group names from the ICHPCGRP block is copied into AIDLSEC in the authorization ID list.

Section 3

Section 3 performs the following steps:

1. The SQL ID is set equal to the primary ID.
2. If the TSO data set name prefix is a valid primary or secondary ID, the SQL ID is replaced with the TSO data set name prefix. Otherwise, the SQL ID remains set to the primary ID.

In the sample sign-on routine (DSN3SSGN): The three sections of the sample sign-on routine perform the following functions:

Section 1

Section 1 does not change the primary ID.

Section 2

Section 2 sets the SQL ID to the value of the primary ID.

Section 3

Section 3 tests RACF options and makes the following changes in the list of secondary IDs, which is initially blank:

• If RACF is not active, the list remains blank.
• If the list of groups option is active, section 3 attempts to find an existing ACEE from which to copy the authorization ID list.
  • If AIDLACEE contains a valid ACEE, it is used.

    Otherwise, look for a valid ACEE chained from the TCB or from the ASXB or, if no usable ACEE exists, issue RACROUTE to have RACF build an ACEE structure for the primary ID.

    Copy the list of group names from the ACEE structure into the secondary authorization list.

  • If the exit issued RACROUTE to build an ACEE, another RACROUTE macro is issued and the structure is deleted.
• If a list of secondary authorization IDs has not been built, and AIDLSAPM is not zero, the data that is pointed to by AIDLSAPM is copied into AIDLSEC.