Version 4.2.6 for Mainframes (Update)	SEARCH   INDEX   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT

This section describes the application programming interfaces (APIs) available with Natural Security. It covers the following topics:

• Overview of Subprograms

• Subprogram NSC---L

• Subprogram NSC---P

• Subprogram NSC---SP

• Subprogram NSC----P

• 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 NSCUS

• Subprogram NSCUT

• Subprogram NSCXLO

• Subprogram NSCXR

• Subprogram NSCXRIER

• Subprogram NSCXRUSE

• Subprogram SECNOTE

Overview of Subprograms

Natural Security provides a number of application programming interfaces (APIs), that is, subprograms which may be used to access Natural Security maintenance and retrieval functions from outside the Natural Security library SYSSEC.

Use of the subprograms is controlled by the general option "Free Access to Functions via APIs" (which is described in the section Administrator Services).

On the Main Menu, you enter code "A" for "Administrator Services". The Administrator Services Menu will be displayed.

Note:
Access to Administrator Services may be restricted (as explained in the section Administrator Services).

On the Administrator Services Menu 2, you select "Application Programming Interfaces". A list of the interface subprograms along with examples and explanatory online texts will be displayed.

The following subprograms are available:

Subprograms for Access Verification:

Subprograms for User Authentication:

Subprograms for Administrator Services:

Subprograms for Object Maintenance:

Subprograms for Retrieval:

Each subprogram that is to be used must 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.

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.

NSC---L is invoked as follows:

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

Example programs PGM---L and PGM---LM of how to invoke subprogram NSC---L, as well as explanatory texts TXT---L and TXT---LM, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGM---L(M) and TXT---L(M).

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.

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 subprogram NSC---P, as well as an explanatory text TXT---P, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGM---P and TXT---P.

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

NSC---SP is invoked as follows:

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

An example program PGM---SP of how to invoke subprogram NSC---SP, as well as an explanatory text TXT---SP, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGM---SP and TXT---SP.

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.

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 subprogram NSC----P, as well as an explanatory text TXT----P, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGM----P and TXT----P.

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 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;

• 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 Library and User Preset Values) with the the corresponding actual value in user profiles to obtain a list of all user profiles in which the value differs from the preset value.

NSCADM is invoked as follows:

CALLNAT 'NSCADM' NSCADM-PARM PNSC-MESSAGE

Example programs PGMADMnn of how to invoke subprogram NSCADM, as well as explanatory texts TXTADMnn, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMADMnn and TXTADMnn.

Subprogram NSCCHCK

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

NSCCHCK is invoked as follows:

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

An example program PGMCHCK of how to invoke subprogram NSCCHCK, as well as an explanatory text TXTCHCK, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMCHCK and TXTCHCK.

Subprogram NSCDA

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

NSCDA is invoked as follows:

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

An example program PGMDA of how to invoke subprogram NSCDA, as well as an explanatory text TXTDA, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMDA and TXTDA.

Subprogram NSCDA-C

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

NSCDA-C is invoked as follows:

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

An example program PGMDA-C of how to invoke subprogram NSCDA-C, as well as an explanatory text TXTDA-C, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMDA-C and TXTDA-C.

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.

NSCDA-P is invoked as follows:

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

An example program PGMDA-P of how to invoke subprogram NSCDA-P, as well as an explanatory text TXTDA-P, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMDA-P and TXTDA-P.

Subprogram NSCDA-S

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

NSCDA-S is invoked as follows:

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

An example program PGMDA-S of how to invoke subprogram NSCDA-S, as well as an explanatory text TXTDA-S, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMDA-S and TXTDA-S.

Subprogram NSCDAU

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

NSCDAU is invoked as follows:

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

An example program PGMDAU of how to invoke subprogram NSCDAU, as well as an explanatory text TXTDAU, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMDAU and TXTDAU.

Subprogram NSCDAUC

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

NSCDAUC is invoked as follows:

CALLNAT 'NSCDAUC' #PAPPLID #PUSERID #PRC #PPARM1 PNSC-MESSAGE

An example program PGMDAUC of how to invoke subprogram NSCDAUC, as well as an explanatory text TXTDAUC, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMDAUC and TXTDAUC.

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.

NSCDAUP is invoked as follows:

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

An example program PGMDAUP of how to invoke subprogram NSCDAUP, as well as an explanatory text TXTDAUP, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMDAUP and TXTDAUP.

Subprogram NSCDAUS

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

NSCDAUS is invoked as follows:

CALLNAT 'NSCDAUS' #PAPPLID #PUSERID #PRC #PPARM1 PNSC-MESSAGE

An example program PGMDAUS of how to invoke subprogram NSCDAUS, as well as an explanatory text TXTDAUS, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMDAUS and TXTDAUS.

Subprogram NSCDEF

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

NSCDEF is invoked as follows:

CALLNAT 'NSCDEF' POBJID POBJTYPE PRC PNSC-MESSAGE

An example program PGMDEF of how to invoke subprogram NSCDEF, as well as an explanatory text TXTDEF, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMDEF and TXTDEF.

Subprogram NSCDU

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

NSCDU is invoked as follows:

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

An example program PGMDU of how to invoke subprogram NSCDU, as well as an explanatory text TXTDU, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMDU and TXTDU.

Subprogram NSCFI

This subprogram is only available on mainframe 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.

NSCFI is invoked as follows:

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

Example programs PGMFInnn of how to invoke subprogram NSCFI, as well as explanatory texts TXTFInnn, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMFInnn and TXTFInnn.

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

Subprogram NSCLI

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

NSCLI 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 subprogram NSCLI, as well as explanatory texts TXTLInnn, are provided in source form in the library SYSSEC. Example programs PGMDDMnn of how to invoke NSCLI with function code "MD", as well as explanatory texts TXTDDMnn, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMLInnn, TXTLInnn, PGMDDMnn and TXTDDMnn.

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

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:

Subprogram NSCMA

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

NSCMA is invoked as follows:

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

Example programs PGMMAnnn showing how to invoke subprogram NSCMA, as well as explanatory texts TXTMAnnn, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMMAnnn and TXTMAnnn.

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

Subprogram NSCOB

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

NSCOB is invoked as follows:

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

Example programs PGMOB nnn of how to invoke subprogram NSCOB, as well as explanatory texts TXTOBnnn, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMOBnnn and TXTOBnnn .

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

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 subprogram NSCUS, as well as explanatory texts TXTUSnnn, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMUSnnn and TXTUSnnn.

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

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

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

Subprogram NSCUT

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

NSCUT 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 subprogram NSCUT, as well as explanatory texts TXTUTnnn, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMUTnnn and TXTUTnnn.

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

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

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.

NSCXLO 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 subprogram NSCXLO, as well as explanatory texts TXTXLOnn, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMXLOnn and TXTXLOnn.

Subprogram NSCXR

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

NSCXR 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 subprogram NSCXR, as well as explanatory texts TXTXRnnn, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMXRnnn and TXTXRnnn.

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:

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:

Functions Available for a User (US):

Functions Available for a Library (LI):

Functions Available for a DDM (DD):

Functions Available for a File (FI):

Functions Available for a Mailbox (MA):

Functions Available for Logon Error Records (LE):

Functions Available for Logon Records (LR):

Functions Available for Steplibs (ST):

Functions Available for Utilities (UT):

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):

Function Available for External Objects:

Subprogram NSCXRIER

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

NSCXRIER is invoked as follows:

CALLNAT 'NSCXRIER' NSCXRIER-PARM PNSC-MESSAGE

An example program PGMXRIER of how to invoke subprogram NSCXRIER, as well as an explanatory text TXTXRIER, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMXRIER and TXTXRIER.

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 subprogram NSCXRUSE, as well as an explanatory text TXTXRUSE, are provided in source form in the library SYSSEC.

The individual CALLNAT parameters are explained in the source codes of PGMXRUSE and TXTXRUSE.

See also the subprogram NSC---SP.

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:

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

www.softwareag.com

Copyright © 1979-2010 Software AG, Darmstadt, Germany.

SEARCH   INDEX   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT