Application Programming Interfaces

#### Search Results

Search

# Application Programming Interfaces

This section describes the application programming interfaces (APIs) available with Natural Security:

- About Subprograms

- Subprograms for Access Verification and User Authentication

- Subprograms for Administrator Services

- Subprograms for Object Maintenance

- Subprograms for Retrieval

- Subprogram Descriptions

## About Subprograms

Natural Security provides several application programming interfaces (APIs). They are Natural subprograms and can be divided into four categories:

- subprograms for access verification and user authentication;

- subprograms to perform Natural Security Administrator Services functions from outside the Natural Security library `SYSSEC`;

- subprograms to perform Natural Security maintenance functions from outside the Natural Security library `SYSSEC`;

- subprograms to perform Natural Security retrieval functions from outside the Natural Security library `SYSSEC`;

Each subprogram to be used has to be copied into the library in which it is to be executed, or into one of the steplibs concatenated to that library.

Note
The subprograms (with the exception of `SECNOTE`) cannot be invoked from any of the logon-related user exits described in the section User Exits.

To list the APIs:

1. On the Main Menu, select Administrator Services.

   If you are allowed access to Administrator Services, the Administrator Services Menu 1 will be displayed.

2. Press PF8.

3. On the Administrator Services Menu 2, select Application Programming Interfaces.

   A list of the interface subprograms - along with examples and explanatory online texts - will be displayed.

#### Return Code

Several of the subprograms contain the field `PRC`. It contains the return code. This will be `0` if the function was performed successfully. Any other return code nnnn corresponds either to a Natural Security error number or, if prefixed with a hyphen (-), to a Natural system error number. You can display the corresponding message by entering the Natural system command:

- `HELP Unnnn` for a Natural Security message, in the library `SYSSEC`; or

- `HELP nnnn` for a Natural system message.

## Subprograms for Access Verification and User Authentication

These subprograms can be used for the following:

Subprogram | Function
--- | ---
Subprograms for Access Verification
`NSC---L` | Check if logon to a library is allowed, and which modules in a library are available to a user.
`NSCCHCK` | Check if access to external object is allowed.
`NSCDEF` | Check if object is defined to Natural Security.
Subprograms for User Authentication
`NSC---P` | Check if password is valid.
`NSC----P` | Check if password is valid, and change it.
`NSC--PH` | Check if password phrase is valid.
`NSC--PHS` | Check if password phrase is valid, and change it.
`NSC---SP` | Check if password is valid - in RPC server environments.
`NSCSSX` | Check if password is valid - in an LDAP user authentication context.

## Subprograms for Administrator Services

These subprograms can be used to perform various Administrator Services functions:

Subprogram | Function
--- | ---
`NSCADM` | Display General Options; process (ETID-related) logon records; process logon/countersign error records; remove/re-establish maintenance/retrieval sections for individual object types; display users in whose security profiles a value differs from a preset value; list and unlock locked user IDs.
`NSCSSXMN` | Archive/revive LDAP security profile.
`NSCXLI` | Display a single maintenance log record.
`NSCXLO` | Display list of maintenance log records.

## Subprograms for Object Maintenance

These subprograms can be used to perform maintenance functions on security profiles of various object types:

Subprogram | Function
--- | ---
`NSCFI` | Maintenance functions for files.
`NSCLI` | Maintenance functions for libraries.
`NSCMA` | Maintenance functions for mailboxes.
`NSCOB` | Maintenance functions for external objects.
`NSCUS` | Maintenance functions for users.
`NSCUT` | Maintenance functions for utilities.

The use of the subprograms for object maintenance is controlled by the general option Free Access to Functions via APIs (described in the section Administrator Services).

## Subprograms for Retrieval

These subprograms can be used to obtain various kinds of information:

Subprogram | Function
--- | ---
`NSCDA` | Display library security profile.
`NSCDA-C` | Display command restrictions of library security profile.
`NSCDA-P` | Display security options, security limits and session parameters of library security profile.
`NSCDA-S` | Display statement restrictions of library security profile.
`NSCDAU` | Display special-link security profile.
`NSCDAUC` | Display command restrictions of special-link security profile.
`NSCDAUP` | Display security options, security limits and session parameters of special-link security profile.
`NSCDAUS` | Display statement restrictions of special-link security profile.
`NSCDU` | Display user security profile.
`NSCONE` | Display NaturalONE profile.
`NSCXR` | Cross-reference functions.
`NSCXRIER` | Display individual logon error records.
`NSCXRUSE` | Display users with logon error counters and unused user IDs.
`NSCXRUTC` | Display utility functions allowed for a user.
`SECNOTE` | Display security notes of user, library or special-link security profile.
`NSCFI`, `NSCLI`, `NSCMA`, `NSCOB`, `NSCUS`, `NSCUT` | The display functions (function code `DI` - Display security profile) of these subprograms are considered to be retrieval functions.

The use of the subprograms for retrieval is controlled by the general option Free Access to Functions via APIs (described in the section Administrator Services).

## Subprogram Descriptions

This section describes all application programming interfaces in alphabetical order:

- Subprogram NSC---L

- Subprogram NSC---P

- Subprogram NSC--PH

- Subprogram NSC---SP

- Subprogram NSC----P

- Subprogram NSC--PHS

- Subprogram NSCADM

- Subprogram NSCCHCK

- Subprogram NSCDA

- Subprogram NSCDA-C

- Subprogram NSCDA-P

- Subprogram NSCDA-S

- Subprogram NSCDAU

- Subprogram NSCDAUC

- Subprogram NSCDAUP

- Subprogram NSCDAUS

- Subprogram NSCDEF

- Subprogram NSCDU

- Subprogram NSCFI

- Subprogram NSCLI

- Subprogram NSCMA

- Subprogram NSCOB

- Subprogram NSCONE

- Subprogram NSCSSX

- Subprogram NSCSSXMN

- Subprogram NSCUS

- Subprogram NSCUT

- Subprogram NSCXLI

- Subprogram NSCXLO

- Subprogram NSCXR

- Subprogram NSCXRIER

- Subprogram NSCXRUSE

- Subprogram NSCXRUTC

- Subprogram SECNOTE

### Subprogram NSC---L

The subprogram `NSC---L` is used to:

- check whether a specific user is allowed to log on to a specific library;

- ascertain which modules in a library are available to a user.

It is invoked as follows:

    CALLNAT 'NSC---L' PAPPLID PUSERID PRC PPARM1 PNSC-MESSAGE

Example programs `PGM---L` and `PGM---LM` of how to invoke this subprogram, and explanatory texts `TXT---L` and `TXT---LM` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

### Subprogram NSC---P

The subprogram `NSC---P` is used to check if the password supplied together with a user ID is valid.

Note
To perform this function in a Natural RPC server environment, is it recommended that `NSC---SP` (see below) be used instead. To check a password phrase, use `NSC--PH` (see below).

`NSC---P` is invoked as follows:

    CALLNAT 'NSC---P' PUSERID PPASSWORD PUSER_NAME PRC PNSC-MESSAGE

An example program `PGM---P` of how to invoke this subprogram, and an explanatory text `TXT---P` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

Note:
For the execution of this subprogram, the general option Maximum Number of Logon Attempts applies, that is, each invalid password will be considered an unsuccessful logon attempt.

### Subprogram NSC--PH

The subprogram `NSC--PH` is used to check if the password phrase supplied together with a user ID is valid.

It is invoked as follows:

    CALLNAT 'NSC--PH' PUSERID PPASSWORD_PHRASE PUSER_NAME PRC PNSC-MESSAGE PNSC-MESSAGE_2

An example program `PGM--PH` of how to invoke this subprogram, and an explanatory text `TXT--PH` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

Note:
For the execution of this subprogram, the general option Maximum Number of Logon Attempts applies, that is, each invalid password phrase will be considered an unsuccessful logon attempt.

### Subprogram NSC---SP

The subprogram `NSC---SP` is only to be used in Natural RPC server environments. On the whole, it corresponds to `NSC---P` (described above). It is used to check if the password supplied together with a user ID is valid.

It is invoked as follows:

    CALLNAT 'NSC---SP' PUSERID PPASSWORD PLIBRARYID PUSERNAME
                         PPARM1 PRC PNSC-MESSAGE

An example program `PGM---SP` of how to invoke this subprogram, and an explanatory text `TXT---SP` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

Note:
For the execution of this subprogram, the general option Maximum Number of Logon Attempts applies, that is, each invalid password will be considered an unsuccessful logon attempt. In addition, Natural Security will react as if the Lock User Option were set to `X`, that is, it will "remember" unsuccessful logon attempts across sessions. Unlike the Lock User Option, however, the locking of user IDs will not include the user ID as contained in the Natural system variable `*INIT-USER`. When the maximum number of logon attempts is exceeded, the Natural RPC server session will not be terminated.

### Subprogram NSC----P

The subprogram `NSC----P` is used to check if the password supplied together with a user ID is valid; in addition, it is used to change the password.

Note
To perform this function for a password phrase, use `NSC--PHS` (see below).

`NSC----P` is invoked as follows:

    CALLNAT 'NSC----P' PUSERID PPASSWORD(*) PUSER_NAME PPARM PRC PNSC-MESSAGE

An example program `PGM----P` of how to invoke this subprogram, and an explanatory text `TXT----P` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

Note:
For the execution of this subprogram, the general option Maximum Number of Logon Attempts applies, that is, each invalid password will be considered an unsuccessful logon attempt.

### Subprogram NSC--PHS

The subprogram `NSC--PHS` is used to check if the password phrase supplied together with a user ID is valid; in addition, it is used to change the password phrase.

It is invoked as follows:

    CALLNAT 'NSC--PHS' PUSERID PPASSWORD_PHRASE(*) PUSER_NAME PPARM PRC PNSC-MESSAGE PNSC-MESSAGE_2

An example program `PGM--PHS` of how to invoke this subprogram, and an explanatory text `TXT--PHS` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

Note:
For the execution of this subprogram, the general option Maximum Number of Logon Attempts applies, that is, each invalid password phrase will be considered an unsuccessful logon attempt.

### Subprogram NSCADM

The subprogram `NSCADM` is used to:

- display the settings of General Options in Administrator Services;

- process logon records, which is particular relevant for ETID-related logon records;

- process logon/countersign error records;

- remove/re-establish Natural Security maintenance/retrieval sections for: base/compound application profiles and RPC server profiles.

- compare a preset value (as set in the User Preset Values) with the corresponding actual value in user security profiles to obtain a list of all user security profiles in which the value differs from the preset value.

- list locked user IDs, and unlock a user ID.

It is invoked as follows:

    CALLNAT 'NSCADM' PVERSION PPARM PPARM1(*) PLENGTH PRC PNSC-MESSAGE

Example programs `PGMADMnn` of how to invoke this subprogram, and explanatory texts `TXTADMnn` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

The second parameter has to be filled with the function code for the desired function. The following functions are available:

Code | Function
--- | ---
For general options:
`GDO` | Display general options.
`NSF` | Display NSF options.
For logon records:
`LR` | List.
`DR` | Delete.
For logon/countersign error records:
`LE` | List.
`DE` | Delete.
For maintenance/retrieval sections for base/compound application and RPC server profiles:
`DI` | Display.
`DE` | Delete.
For preset-value comparison:
`PR` | Compare.
For locked user IDs:
`LI` | List locked user IDs.
`UL` | Unlock a user ID.

### Subprogram NSCCHCK

The subprogram `NSCCHCK` is used to check whether a specific user is allowed to access a specific external object.

It is invoked as follows:

    CALLNAT 'NSCCHCK' PCLASSID PUSERID POBJID PACCESS-TYPE PRC PPARM1 PNSC-MESSAGE

An example program `PGMCHCK` of how to invoke this subprogram, and an explanatory text `TXTCHCK` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

### Subprogram NSCDA

The subprogram `NSCDA` is used to display the security profile of a library.

It is invoked as follows:

    CALLNAT 'NSCDA' PAPPLID PPARM PRC PTYPE
                      PPARM1 PPARM2 PPARM3 PTEXT(*) PNSC-MESSAGE

An example program `PGMDA` of how to invoke this subprogram, and an explanatory text `TXTDA` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

### Subprogram NSCDA-C

The subprogram `NSCDA-C` is used to display the Command Restrictions part of a library security profile.

It is invoked as follows:

    CALLNAT 'NSCDA-C' PAPPLID PRC PTYPE PPARM1 PNSC-MESSAGE

An example program `PGMDA-C` of how to invoke this subprogram, and an explanatory text `TXTDA-C` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

### Subprogram NSCDA-P

The subprogram `NSCDA-P` is used to display the Security Options, Security Limits and Session Parameters parts of a library security profile.

It is invoked as follows:

    CALLNAT 'NSCDA-P' PAPPLID PRC PTYPE PPARM1 POPRBS(*) PNSC-MESSAGE

An example program `PGMDA-P` of how to invoke this subprogram, and an explanatory text `TXTDA-P` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

### Subprogram NSCDA-S

The subprogram `NSCDA-S` is used to display the Statement Restrictions part of a library security profile.

It is invoked as follows:

    CALLNAT 'NSCDA-S' PAPPLID PRC PTYPE PPARM1 PNSC-MESSAGE

An example program `PGMDA-S` of how to invoke this subprogram, and an explanatory text `TXTDA-S` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

### Subprogram NSCDAU

The subprogram `NSCDAU` is used to display the security profile of a special link.

It is invoked as follows:

    CALLNAT 'NSCDAU' PAPPLID PUSERID PRC
                       PPARM1 PPARM2 PPARM3 PTEXT(*) PNSC-MESSAGE

An example program `PGMDAU` of how to invoke this subprogram, and an explanatory text `TXTDAU` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

### Subprogram NSCDAUC

The subprogram `NSCDAUC` is used to display the Command Restrictions part of a special-link security profile.

It is invoked as follows:

    CALLNAT 'NSCDAUC' PAPPLID PUSERID PRC PPARM1 PNSC-MESSAGE

An example program `PGMDAUC` of how to invoke this subprogram, and an explanatory text `TXTDAUC` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

### Subprogram NSCDAUP

The subprogram `NSCDAUP` is used to used to display the Security Options, Security Limits and Session Parameters parts of a special-link security profile.

It is invoked as follows:

    CALLNAT 'NSCDAUP' PAPPLID PUSERID PRC PPARM1 POPRBS(*) PNSC-MESSAGE

An example program `PGMDAUP` of how to invoke this subprogram, and an explanatory text `TXTDAUP` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

### Subprogram NSCDAUS

The subprogram `NSCDAUS` is used to used to display the Statement Restrictions part of a special-link security profile.

It is invoked as follows:

    CALLNAT 'NSCDAUS' PAPPLID PUSERID PRC PPARM1 PNSC-MESSAGE

An example program `PGMDAUS` of how to invoke this subprogram, and an explanatory text `TXTDAUS` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

### Subprogram NSCDEF

The subprogram `NSCDEF` is used to check whether a specific object is defined under Natural Security, that is, whether a security profile for the object exists.

It is invoked as follows:

    CALLNAT 'NSCDEF' POBJID POBJTYPE PRC PNSC-MESSAGE PPARM1

An example program `PGMDEF` of how to invoke this subprogram, and an explanatory text `TXTDEF` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

### Subprogram NSCDU

The subprogram `NSCDU` is used to display a user security profile.

It is invoked as follows:

    CALLNAT 'NSCDU' PUSERID PPARM PRC PPARM1 PPARM2 PPARM3
                      PTEXT(*) PNSC-MESSAGE

An example program `PGMDU` of how to invoke this subprogram, and explanatory text `TXTDU` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

### Subprogram NSCFI

This subprogram is only available on z/OS computers, and it can only be applied to file security profiles. For DDM security profiles, you use the subprogram `NSCLI` (see below).

The subprogram `NSCFI` is used to perform maintenance/retrieval functions for file security profiles from outside of the library `SYSSEC`.

It is invoked as follows:

    CALLNAT 'NSCFI' PFUNCTION PFILEID PFILEID2 PRC PPFKEY(*)
                      PPARM PPARM1 PPARM2 PTEXT(*) PNSC-MESSAGE

Example programs `PGMFInnn` of how to invoke this subprogram, and explanatory texts `TXTFInnn` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

The first parameter (`PFUNCTION`) has to be filled with the function code for the desired function. The following functions are available:

Code | Function
--- | ---
`AD` | Add file
`CL` | Cancel link between library and file
`CO` | Copy file
`DE` | Delete file
`DI` | Display file
`MO` | Modify file (including all components of its security profile)
`RE` | Establish read-link between library and file
`UP` | Establish update-link between library and file

### Subprogram NSCLI

The subprogram `NSCLI` is used to perform maintenance/retrieval functions for library security profiles from outside of library `SYSSEC`.

It is invoked as follows:

    CALLNAT 'NSCLI' PFUNCTION PLIBID PLIBID2 PLIBTYPE PRC PPFKEY(*)
                      PPARM PPARM1 PPARM2 PTEXT(*) PPARM3 PPARM4
                      PPARM5 PPARM6 POPRB(*) PNSC-MESSAGE

Example programs `PGMLInnn` of how to invoke this subprogram, and explanatory texts `TXTLInnn`, as well as example programs `PGMDDMnn` of how to invoke it with function code `MD`, and corresponding explanatory texts `TXTDDMnn` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

The first parameter (`PFUNCTION`) has to be filled with the function code for the desired function. The following functions are available:

Code | Function
--- | ---
`AD` | Add library
`CL` | Cancel link between user and library
`CO` | Copy library
`DE` | Delete library
`DI` | Display library
`DL` | Display special link between user and library
`DM` | Display allowed/disallowed modules
`ET` | Get library ID via ETID
`LK` | Link user to library
`MD` | Maintain DDM profile; see also below (this function is not available on z/OS)
`MM` | Modify allowed/disallowed modules
`MO` | Modify library (including all components of its security profile)
`SL` | Establish special link between user and library
`TL` | Temporarily lock link between user and library
`UC` | Update all "modified" command processors in the library

If `PFUNCTION` is filled with function code `MD`, the `PSUBFUNC` part of the parameter `PPARM` has to be filled with the code for the desired subfunction. The following subfunctions are available:

Code | Subfunction
--- | ---
`AD` | Add DDM profile
`CL` | Cancel link between library and DDM profile
`CO` | Copy DDM profile
`DE` | Delete DDM profile
`DI` | Display DDM profile
`MO` | Modify DDM profile
`RE` | Establish read-link between library and DDM profile
`UP` | Establish update-link between library and DDM profile

### Subprogram NSCMA

The subprogram `NSCMA` is used to perform maintenance/retrieval functions for mailbox security profiles from outside of the library `SYSSEC`.

It is invoked as follows:

    CALLNAT 'NSCMA' PFUNCTION POBJID POBJID2 PRC PPFKEY(*)
                      PPARM PPARM1 PPARM2 PTEXT1(*) PTEXT2(*) PNSC-MESSAGE

Example programs `PGMMAnnn` of how to invoke this subprogram, and explanatory texts `TXTMAnnn` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

The first parameter (`PFUNCTION`) has to be filled with the function code for the desired function. The following functions are available:

Code | Function
--- | ---
`AD` | Add mailbox
`CO` | Copy mailbox
`DE` | Delete mailbox
`DI` | Display mailbox
`MO` | Modify mailbox (including all components of its security profile)
`RE` | Rename mailbox

### Subprogram NSCOB

The subprogram `NSCOB` is used to perform maintenance/retrieval functions for external object security profiles from outside of library `SYSSEC`.

It is invoked as follows:

    CALLNAT 'NSCOB' PFUNCTION PCLASSID POBJID POBJID2 PRC PPFKEY(*)
                      PPARM PPARM1 PPARM2 PTEXT(*) PNSC-MESSAGE

Example programs `PGMOBnnn` of how to invoke this subprogram, and explanatory texts `TXTOBnnn` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

The first parameter (`PFUNCTION`) has to be filled with the function code for the desired function. The following functions are available:

Code | Function
--- | ---
`AD` | Add external object
`CL` | Cancel link between user and external object
`CO` | Copy external object
`DE` | Delete external object
`DI` | Display external object
`DL` | Display link between user and external object
`LK` | Link user to external object
`MO` | Modify external object (including all components of its security profile)

### Subprogram NSCONE

The subprogram `NSCONE` is used to display a NaturalONE profile, that is, the Natural Server view and Eclipse Navigator view options and actions allowed/disallowed for a specific library and user.

It is invoked as follows:

    CALLNAT 'NSCONE' PFUNCTION PUSER PGROUP PLIBRARY PFUSER(*) PRC
                        PPARM PPARM1 PPARM2 PPARM3 PNSC-MESSAGE

Example programs `PGMONEnn` of how to invoke this subprogram, and explanatory texts `TXTONEnn` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

### Subprogram NSCSSX

The subprogram `NSCSSX` is used to check if the password supplied together with the user ID is valid.

A prerequisite for the use of this subprogram is that the user authentication via an LDAP server has been activated; see Authentication Options (LDAP).

`NSCSSX` is invoked as follows:

    CALLNAT 'NSCSSX' PUSERID PPASSWORD PNSC-USERID PNSC-USERNAME
                      PNSC-USERTYPE PPARM PRC PNSC-MESSAGE

An example program `PGMSSX01` of how to invoke this subprogram, and an explanatory text `TXTSSX01` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

Note:
For the execution of this subprogram, the general option Maximum Number of Logon Attempts applies, that is, each invalid password will be considered an unsuccessful logon attempt.

### Subprogram NSCSSXMN

The subprogram `NSCSSXMN` is used to archive and revive an LDAP security profile.

A prerequisite for the use of this subprogram is that the LDAP security profile exists in archived or revived form; see Authentication Options (LDAP).

`NSCSSXMN` is invoked as follows:

    CALLNAT 'NSCSSXMN' PFUNCTION PPROFILE-ID PRC

An example program `PGMSSX02` of how to invoke this subprogram, and an explanatory text `TXTSSX02` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

### Subprogram NSCUS

The subprogram `NSCUS` is used to perform maintenance/retrieval functions for user security profiles from outside of library `SYSSEC`.

Note
`NSCUS` cannot be used for private libraries which may be attached to user security profiles; for maintenance/retrieval of private libraries, you use subprogram `NSCLI`.

`NSCUS` is invoked as follows:

    CALLNAT 'NSCUS' PFUNCTION PUSERID PUSERID2 PRC PPFKEY(*)
                      PPARM PPARM1 PPARM2 PTEXT(*) PPARM3 PPARM4 PNSC-MESSAGE

Example programs `PGMUSnnn` of how to invoke this subprogram, and explanatory texts `TXTUSnnn` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

The first parameter (`PFUNCTION`) has to be filled with the function code for the desired function. The following functions are available:

Code | Function
--- | ---
`AD` | Add user
`AM` | Multiple add user
`CO` | Copy user
`DE` | Delete user
`DI` | Display user
`EG` | Edit group members
`ET` | Get user ID via ETID
`MO` | Modify user (including all components of his/her security profile)

Note:
The user maintenance function Copy User's Links is not available via `NSCUS`.

For function code `EG`, the following subfunctions are available:

Code | Subfunction
--- | ---
`AD` | Add users to a group
`DE` | Delete users from a group
`LI` | List group members

### Subprogram NSCUT

The subprogram `NSCUT` is used to perform maintenance/retrieval functions for utility security profiles from outside of library `SYSSEC`.

It is invoked as follows:

    CALLNAT 'NSCUT' PFUNCTION PUTILITY PUSER PLIBRARY PRC PPFKEY(*)
                      PPARM PPARM1 PPARM2 PTEXT(*) PNSC-MESSAGE

Example programs `PGMUTnnn` of how to invoke this subprogram, and explanatory texts `TXTUTnnn` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

The first parameter (`PFUNCTION`) has to be filled with the function code for the desired function. The following functions are available:

Code | Subfunction
--- | ---
`AD` | Add utility
`DE` | Delete utility
`DI` | Display utility
`MO` | Modify utility (including all components of its security profile)

Please note that the components of the security profiles are different for each utility; see also the sources of `PGMUTnnn`.

### Subprogram NSCXLI

The subprogram `NSCXLI` is used to display a single maintenance log record, created by Natural Security if the general option Logging of Maintenance Functions is active.

It is invoked as follows:

    CALLNAT 'NSCXLI' PFUNCTION PSELECT-TYPE POBJ-ID POBJ-ID2 PTIMESTMP PPARM PRC PNSC-MESSAGE PLOG-HEADER
                     XPARM1 PPARM1 XPARM2 PPARM2 XPARM3 PPARM3 XPARM4 PPARM4 XPARM5 PPARM5 XPARM6 PPARM6 XTEXT PTEXT

Example programs `PGMXLInn` of how to invoke this subprogram, and explanatory texts `TXTXLInn` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

### Subprogram NSCXLO

The subprogram `NSCXLO` is used to read maintenance log records, which are created by Natural Security if the general option Logging of Maintenance Functions is active.

It is invoked as follows:

    CALLNAT 'NSCXLO' PFUNCTION PSELECT-TYPE PSTART-OBJ-ID
                     PFROMTIMESTMP PTOTIMESTMP PRC PPARM PPARM1(*) PNSC-MESSAGE

Example programs `PGMXLOnn` of how to invoke this subprogram, and explanatory texts `TXTXLOnn` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

### Subprogram NSCXR

The subprogram `NSCXR` is used to perform cross-reference functions for security profiles from outside of library `SYSSEC`.

It is invoked as follows:

    CALLNAT 'NSCXR' POBJ-TYPE POBJ-ID PLINK-ID PRC SUB-TYPE
                    PPARM PPARM2(*) PNSC-MESSAGE

Example programs `PGMXRnnn` of how to invoke this subprogram, and explanatory texts `TXTXRnnn` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

The first parameter (`POBJ-TYPE`) has to be filled with the code for the type of object for which a function is to be performed:

Code | Object Type
--- | ---
`US` | User
`LI` | Library
`DD` | DDM (this object type is not available on z/OS)
`FI` | File (this object type is only available on z/OS)
`MA` | Mailbox
`LE` | Logon error record
`LR` | Logon record
`ST` | Steplib
`UT` | Utility
`CP` | Command processor
`PE` | Predict external object (this object type is only available if Predict is installed)
`PF` | Predict function (this object type is only available if Predict is installed)
`PL` | Predict 3GL library (this object type is only available if Predict is installed)
`PO` | Predict documentation object (this object type is only available if Predict is installed)
`SF` | System file

For the individual object types listed above, the following functions can be performed by filling the parameter `SUB-TYPE` with one of the following function codes:

Function Available for Every Object Type:
Code | Function
--- | ---
`TR` | Translate the 2-character object-type code into the corresponding object type.

Functions Available for a User (US):
Code | Function
--- | ---
`*` | List all users.
`A` | List all users of type Administrator.
`P` | List all users of type Person.
`M` | List all users of type Member.
`T` | List all users of type Terminal.
`G` | List all users of type Group.
`B` | List all users of type Batch.
`GR` | List all groups the user belongs to.
`GP` | List all privileged groups the user belongs to.
`GM` | List all users contained in the group.
`BU` | List all users in whose security profiles the batch user ID is specified.
`NI` | Retrieve the user ID belonging to a specified user name.
`L*` | List all users and all libraries to which they are linked directly.
`LA` | List all libraries available to the user.
`LL` | List all libraries to which the user is linked.
`LD` | List all libraries to which the user is linked directly.
`LG` | List all libraries to which the user is linked by means of a group.
`LP` | List all libraries to which the user is linked by means of a privileged group.
`OW` | List all security profiles owned by the user.
`DD` | List all DDMs available to the user (this function is not available on z/OS).
`DL` | List all DDMs available to the user by means of a special link (this function is not available on z/OS).
`FI` | List all files to which the user's private library is linked (this function is only available on z/OS).
`UT` | List all utility profiles which apply to the user.
`TD` | Retrieve the Time Differential and Time Zone settings of the user's security profile.

Functions Available for a Library (LI):
Code | Function
--- | ---
`*` | List all libraries and users' private libraries.
`L` | List all libraries.
`U` | List all users' private libraries.
`NI` | Retrieve the library ID belonging to a specified library name.
`DD` | List all DDMs to which the library is linked (this function is not available on z/OS).
`LD` | List all DDMs to which the library is linked by means of a special link (this function is not available on z/OS).
`FI` | List all files to which the library is linked (this function is only available on z/OS).
`NO` | List allowed/disallowed modules.
`SM` | Retrieve information on users' access rights to a single module in the library.
`US` | List all users linked to the library.
`UT` | List all utility profiles which apply to the library.
`CP` | List all command processors for the library that have a specific status.
`GL` | List all library security profiles in which an FDIC or FUSER specification is made.
`GD` | List all library security profiles in which an FDIC specification is made.
`GU` | List all library security profiles in which an FUSER specification is made.

Functions Available for a DDM (DD):
Code | Function
--- | ---
`*` | List all defined DDMs (that is, DDMs for which security profiles exist).
`UN` | List all undefined DDMs (that is, DDMs for which no security profiles exist).
`DD` | List all defined and undefined DDMs.
`P` | List all DDMs with external status PUBLIC.
`A` | List all DDMs with external status ACCESS.
`U` | List all DDMs with external status PRIVATE.
`ND` | List all DDM security profiles for which no corresponding DDMs exist.
`LI` | List all libraries which are linked to the DDM.
`US` | List all users which are linked to the DDM.
`SL` | List all DDM definitions in special-link security profiles.
`X` | List all DDM definitions in library and special-link security profiles.

Functions Available for a File (FI):
Code | Function
--- | ---
`PU` | List files of type PUBLIC.
`AC` | List files of type ACCESS.
`UP` | List files of type PRIVATE.
`DD` | List files with existing DDM.
`ND` | List files with no DDM.
`UN` | List undefined files.
`LI` | List libraries to which the specified file is linked.
`US` | List users whose private libraries are linked to the specified file.

Functions Available for a Mailbox (MA):
Code | Function
--- | ---
`LI` | List all libraries to which the mailbox is assigned.
`US` | List all users to which the mailbox is assigned.

Functions Available for Logon Error Records (LE):
Code | Function
--- | ---
`P` | List logon error records, in order of TP user IDs.
`T` | List logon error records, in order of terminal IDs.

Functions Available for Logon Records (LR):
Code | Function
--- | ---
`L` | List logon records, in order of library IDs.
`U` | List logon records, in order of user IDs.
`D` | List logon records, in order of logon date.
`LX` | List logon records to undefined libraries (in order of library IDs).
`UX` | List logon records of undefined users (in order of user IDs).

Functions Available for Steplibs (ST):
Code | Function
--- | ---
`*` | List all steplibs.
`LK` | List protected steplibs.
`NN` | List public steplibs.
`SL` | List special-linked steplibs.

Functions Available for Utilities (UT):
Code | Function
--- | ---
`LI` | List all library-specific utility profiles defined for the utility.
`US` | List all user-specific utility profiles defined for the utility.
`UT` | List all utility profiles defined for the utility.
`blank` | List all utility profiles defined for all utilities.

Functions Available for Command Processors (CP):
For a command processor, `NSCXR` will list all libraries and users for the command processor (without any `SUB-TYPE` specification being required).

Functions Available for Predict Objects (PE, PF, PL, PO):
For each of the four Predict object types, `NSCXR` will list all objects of that type (without any `SUB-TYPE` specification being required).

Functions Available for System Files (SF):
Code | Function
--- | ---
`FN` | List all libraries of the current FNAT system file which are not defined in Natural Security.
`FU` | List all libraries of the current FUSER system file which are not defined in Natural Security.

Function Available for External Objects:
Code | Function
--- | ---
`LU` | List all users who are linked to the external object.

### Subprogram NSCXRIER

The subprogram `NSCXRIER` is used to display individual logon error records (similar to the Logon/Countersign Errors function Display individual error records).

It is invoked as follows:

    CALLNAT 'NSCXRIER' POBJID PPARM PPARM1(*) PRC PNSC-MESSAGE

An example program `PGMXRIER` of how to invoke this subprogram, and an explanatory text `TXTXRIER` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

### Subprogram NSCXRUSE

The subprogram `NSCXRUSE` is used in conjunction with the Lock User Option set to `X` to obtain a list of users whose logon error counters are greater than `0`.

It is also is used in conjunction with the general option Record Each User's Logon Daily. When this option is active, `NSCXRUSE` can be used to display the IDs of users who have not logged on to Natural since a specified date.

`NSCXRUSE` is invoked as follows:

    CALLNAT 'NSCXRUSE' POBJ-TYPE POBJ-ID PRC PSUBTYPE PPARM PPARM2(*) PNSC-MESSAGE

An example program `PGMXRUSE` of how to invoke this subprogram, and an explanatory text `TXTXRUSE` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

See also the subprogram `NSC---SP`.

### Subprogram NSCXRUTC

The subprogram `NSCXRUTC` is used in to obtain a list of all utility functions which are allowed for a user.

It is invoked as follows:

    CALLNAT 'NSCXRUTC' PFUNCTION PUTILITY-ID PUSER PNEXT-VALUE PPARM PPARM-D(*) PRC PNSC-MSG

An example program `PGMXRUTC` of how to invoke this subprogram, and an explanatory text `TXTXRUTC` are provided in source form in the library `SYSSEC`. They include descriptions of the individual `CALLNAT` parameters.

### Subprogram SECNOTE

The subprogram `SECNOTE` is used to display the Security Notes part of a security profile. It can be applied to a user, group, library or special-link security profile.

The object module of `SECNOTE` is stored in the library `SYSTEM`. The source code of `SECNOTE` is not available.

`SECNOTE` has to be invoked with the following parameters:

Parameter | Explanation
--- | ---
`PTYPE` (A1) | With this parameter, you specify the type of object whose Security Notes are to be read. Valid values for `PTYPE` are: `U` = User. The current content of the Natural system variable `*USER` determines which user's Security Notes will be read. `L` = Library. The current content of the Natural system variable `*APPLIC-ID` determines which library's Security Notes will be read. `G` = Group. The current content of the Natural system variable `*GROUP` determines which user's/group's Security Notes will be read. `S` = Special Link. The current contents of the Natural system variables `*GROUP` and `*APPLIC-ID` determine which special link's Security Notes will be read.
`PNOTES` (A60/8) | On return from `SECNOTE`, this parameter contains the Security Notes.
`PRC` (N4) | This parameter contains the return code from `SECNOTE`: 0 = Security Notes have been read. 860 = `PTYPE` contains an invalid code. 806 = Library does not exist (is not defined to Natural Security). 861 = User has no special link to library. 873 = User does not exist (is not defined to Natural Security).

The above-mentioned system variables are described in the Natural System Variables documentation.

### On this page

- About Subprograms
- Subprograms for Access Verification and User Authentication
- Subprograms for Administrator Services
- Subprograms for Object Maintenance
- Subprograms for Retrieval
- Subprogram Descriptions