Initial authorization function (function code X'00')

The initial authorization function allows you to either reject or limit the scope of a search. For example, you might use initial authorization to reject a search based on a search's originating logical unit (OLU) or its destination logical unit (DLU) because the OLU or the DLU is not authorized to use the network.

Or, you might use initial authorization to limit the scope of a search to the domain of a node, because a resource resides in that node's domain, and further searching would be pointless.

The function provided by this exit is applicable only for new search requests with:

Application general data stream (GDS) variable CDINIT
Application GDS variable INIT_OTHER_CD
No application GDS variable

These types of Application GDS variables generally flow when the search request will result in a session setup (CDINIT, IOCDINIT) or when the search is initiated by network management (no application GDS variables).

Table Table 1 correlates exit return codes and exit sense codes with the search steps performed by directory services following initial authorization. A copy of the application GDS variable is supplied to the exit if application GDS variable support is indicated by the exit during begin processing.

Table 1. Exit return codes, exit sense codes, and VTAM search steps
Exit return code	EXIT	Directory services search steps performed
Exit return code	Sense code	Domain search	APPN directed search	APPN network broadcast	Subarea search of this node	Subarea search of other nodes	Rejected search
0	X'00000000'	X	X	X	X	X
4	X'080A000D'						X
8	X'00000000'	X
12	X'00000000'	X			X
16	X'00000000'	X	X	X		X
20	X'00000000'	X	X	X	X
24	X'00000000'	X	X	X
28	X'00000000'	X			X	X
32	X'00000000'	Directed searches only
36	X'00000000'	Use search task list. See Table 1.
40	X'00000000'	Fail this directed search only. Valid only on redrive.
None of the above	X'080A000D'						X

If the user routine returns a return code corresponding to the None of the above entry in Table 1, VTAM® issues message IST1183I.

Although the exit can limit the scope of a search performed by VTAM, it is not allowed to expand the scope. For example, if VTAM receives a request that does not allow the subarea to be searched, but the exit indicates that a subarea search is allowed, a subarea search is not performed.

The exit can limit the scope of the search performed by VTAM by using return code 36 and turning off individual search tasks in the Search Task List. The exit is allowed to turn off any of the tasks in the list but is not allowed to turn on any task that is not already turned on. Any additional search tasks that the exit attempts to add will be ignored. Table 1 explains the individual search task that can be controlled by the exit.

Guideline: Turning off search tasks, using the Search Task List, without fully understanding the network configuration and the dynamics of APPN searching can result in failed searches or other unexpected results. This function should be used with extreme caution.

When the exit is called for initial authorization with an alias DLU NETID value, the exit can indicate the real NETID value on the reply. If the exit determines that the NETID value in the CV82 vector is the real value, the exit can set the NETID authentic bit in the search task options to indicate that the NETID value is the real value. If the exit determines that a different NETID value should be used as the real NETID value, the exit can rebuild the DLU FIND control vector 82 with the real NETID value and set the NETID authentic bit in the search task options, indicating that the NETID value is the real value. The name cannot be changed; only the NETID value can be changed. If the NETID field length changes, the CV82 length must also be changed to match. Padding was added to the DLU area to accommodate the expansion of the CV82 vector length to a maximum 17 characters. Only the CV82 vector can be changed.