Verbs and Built-in Functions › &SECCALL

&SECCALL

Communicates with the Userid Access Security Subsystem (UAMS) or your installation security exit.

&SECCALL ADD USERID=userid
             PWD=password
             FIELDS={ (nnnn,...,nnnn) | * }
           [ TYPE={ USER | GROUP } ]
           [ PREFIX=prefix ]

&SECCALL CHANGE USERID=userid 
              [ PWD=password ]
              [ NEWPWD=newpassword ]
              [ FIELDS={ (nnnn,...,nnnn) | * } |
                DETAILS={YES | NO } ]
              [ PREFIX=prefix ]

&SECCALL CHECK USERID=userid
               PWD=password

&SECCALL DELETE USERID=userid

&SECCALL EXIT DATA={ xxx ...  xxx } |
              VARS={ xxx | (xxx,...,xxx) } |
              prefix* [ RANGE=( start,end ) ] |
              ARGS [ RANGE=( start,end ) ]

&SECCALL GET USERID=userid
             FIELDS={ (nnnn,...,nnnn) | * }
           [ OPT={ KEQ | KGT | KLT } ]
           [ PREFIX=prefix ]

&SECCALL QUERY [ PREFIX=prefix ]
               [ FIELDS={ (nnnn,...,nnnn) | * } ]

&SECCALL UPDATE USERID=userid
                FIELDS={ (nnnn,...,nnnn) |  * }
              [ PREFIX=prefix ]

The &SECCALL verb provides NCL with a method of communication with the security subsystem or security exit. Security is provided for the use of functions that potentially update the security definition of a user, that is, ADD, UPDATE, and DELETE. The CHANGE function is restricted to changing the issuer's user password unless the user is authorized for UAMS. The QUERY function returns the attributes that the user is using in their currently active region.

Examples: &SECCALL

&SECCALL ADD USERID=userid PWD=password FIELDS=*

&SEC0010 = NAME
&SEC0012 = LOCATION 
&SEC0013 = 123-4567 
&SECCALL CHANGE USERID=&USERID PWD=password +
                NEWPWD=newpwd DETAILS=YES

&SECCALL CHECK USERID=&USERID PWD=password 
&SECCALL DELETE USERID=userid

&SECCALL GET USERID=userid FIELDS=(0010,0012,0013) OPT=KEQ

&SEC0010 = NEW-NAME 
&SEC0012 = NEW-LOCATION 
&SEC0013 = 123-4567 
&SECCALL UPDATE USERID=userid FIELDS=(0010,0012,0013)

&A = PARM1
&B = PARM2 
&C = PARM3 
&SECCALL EXIT VARS=(A,B,C)

Notes:

&SECCALL is particularly useful from EASINET procedures, where it may be used to verify user ID privileges, validity, and passwords before passing the user to a selected application.

&SECCALL is designed to shield the issuing NCL procedure from any knowledge of the type of security subsystem in operation, and provides the same function whether UAMS is in use or an installation-provided security exit is active. If a security exit is provided, &SECCALL causes a call to that exit.

Note: For more information about parameters passed to the exit and information expected from the exit, see the Security Guide.

&SECCALL CHECK function can validate access by a user from the IP host to the local port. This verification is controlled by the system parameter IPCHECK=REGISTER | NONE, which is set only during system initialization. If a user is successfully validated by &SECCALL CHECK, with IPCHECK set to REGISTER, then the system associates their user ID with the IP connection.

IPCHECK=REGISTER results in user IDs being recorded for IP connections by product region signon and &SECCALL CHECK processing.

Structured Fields:

All user ID security attributes use structured fields to exchange data between NCL and the security subsystem or security exit.

All user variables referring to structured fields that are exchanged between NCL and the security subsystem are in the form &prefixnnn where prefix is defined by the PREFIX operand and nnn refers to a structured field that is defined for your product region. (Structured fields referring to components and applications that are not licensed, or that have been excluded, are not available from the security subsystem.)

For example, structured field number 0010 represents the USERID NAME. On completion of &SECCALL GET USERID=userid FIELDS=0010, a variable exists called &SEC0010, containing the user ID of the user for which information was requested.

If a particular structured field contains more than one subfield, one variable is returned for each subfield. In this case the variable representing the first subfield is named in the format described previously, and the remaining subfields are returned in variable names in the format:

&SECxxxxB 
&SECxxxxC 
... 
&SECxxxxZ

For example, structured field number 0016 represents the terminals to which a user is restricted and includes three subfields. On completing &SECCALL GET USERID=userid FIELDS=0016, three variables exist, in the format:

&SEC0016
&SEC0016B
&SEC0016C

Optional features can also generate structured fields to represent feature-dependent user ID attributes or privileges.

Note: For more information, see the Security Guide.