Application Programming Interface

The programs described in this document can be used in Natural applications (or in Open NSPF routines) to access Natural ISPF internal information.

All programs and required Natural ISPF modules are loaded into the Exit Library and into the library SYSTEM. If you wish to use the API programs, it is strongly recommended that you define either SYSTEM or SYSISPE as STEBLIB for your application.

This document covers the following topics:

ISP-U000 - Current Session Program

This program is supplied in object form only. It is a Natural subprogram which returns information about the current Natural ISPF session and can be called from user programs outside Natural ISPF.

The following parameters must be defined:

Parameter Format Type Meaning
#OBJECT (A2) O Contains 2-character abbreviation of the object type. For a list of possible values, see the Table of Exits and Object Abbreviations in section User Exits in the Natural ISPF Administration Guide.
#FUNCTION (A2) O Contains 2-character abbreviation of the function currently executed.
#SES-DATA (A253) O Contains all parameters; must be redefined according to object type. A special local data area is delivered in source form for this redefinition.

Example

The following example is a short Natural macro object which users can call using the COPY MACRO command from an edit session. It generates a program header and uses program ISP-U000 to obtain the name and library of the program being edited: 

  § *
  § * MACRO GENERATES A STANDARD PROGRAM HEADER FOR THE PROGRAM
  § * BEING CURRENTLY EDITED
  § *
  § DEFINE DATA
  § LOCAL USING ISPN---L  /* Redefinition of Natural data
  § LOCAL
  § 1 #OBJECT (A2)
  § 1 #FUNCTION(A2)
  § 1 #DATA (A253)
  § 1 #PROGRAM (A8)
  § 1 #TEXT (A50/5)
  § 1 #I (N2)
  § END-DEFINE
  § *
  § * GET NATURAL SESSION DATA
  § *
  § CALLNAT 'ISP-U000' #OBJECT #FUNCTION #DATA
  § MOVE #DATA TO #SES-DATA-N          /* Move to redefinition
  § MOVE #MEMBER TO #PROGRAM
  § SET KEY PF3
  § SET CONTROL 'WL70C12B005/005F'
  § INPUT (AD=MIL'_')
  § WITH TEXT '----- PROGRAM HEADING INFORMATION -------------'
  § 'PROGRAM:' #PROGRAM (AD=OI)
  § 'LIBRARY:' #LIBRARY (AD=OI)
  § / 'PURPOSE:' #TEXT (1)
  § / ' ' #TEXT (2)
  § / ' ' #TEXT (3)
  § / ' ' #TEXT (4)
  § / ' ' #TEXT (5)
  § IF #TEXT(1) = ' '
  § REINPUT WITH TEXT 'PURPOSE IS REQUIRED'
  § END-IF
  ***********************************************************************
  * PROGRAM: §#PROGRAM DATE CREATED: §*DATD BY: §*USER
  * ---------------------------------------------------------------------
  * PURPOSE:
  § FOR #I = 1 TO 5
  § IF #TEXT(#I) NE ' '
  * §#TEXT(#I)
  § END-IF
  § END-FOR
  * ---------------------------------------------------------------------
  * PROGRAM HISTORY
  * DATE USER-ID REF-NO DESCRIPTION
   ***********************************************************************
  *

The following figure shows the result of the INPUT statement in the macro when the program is invoked from an edit session with program NEWPROG in library NSPFWORK: 

  EDIT-NAT:NSPFWORK(NEWPROG)-Program->Struct-Free-29K - >>> Versioning is invoked
   COMMAND===> COPY MAC MAC-HEAD                                  SCROLL===> CSR
  ****** ****************************** top of data *****************************
  ****** **************************** bottom of data ****************************
  
       +-------------------------------------------------------------------+
       ! ----- PROGRAM HEADING INFORMATION -------------                   !
       ! PROGRAM: NEWPROG  LIBRARY: NSPFWORK                               !
       ! PURPOSE: This program demonstrates something _____________        !
       !          _________________________________________________        !
       !          _________________________________________________        !
       !          _________________________________________________        !
       !          _________________________________________________        !
       !                                                                   !
       ! Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10- !
       !       Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  !
       +-------------------------------------------------------------------+
  
  
  
  
  
  Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
        Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

Another useful example called COPYSYS can be found in the Example Library. This program copies a member which is edited to the library SYSLIB.

ISP-U001 - Access Shortlibs Program

This program allows user programs to access short library names defined in Natural ISPF either in the user profile or in the global shortlib table. If an entry is found, the data set name and volser of the data set is returned.

Parameter Format Type Meaning
#IN-SHORT (A2) I 2-byte library abbreviation.
#OUT-DSN (A44) O Data set name, if given abbreviation was found.
#OUT-VOLSER (A6) O Volser, if defined in profile.

ISP-U002 - Retrieve Error Texts Program

This program can be used to retrieve error texts from the Natural ISPF Error Message Library SYSISPSx (where x is the current language code). If a text is not found for the current language code, the English text is returned. Parameters can be replaced in the error text.

This program can only be used by Open NSPF programs, which are executed from SYSLIB. This program will not work if invoked from any user application.

Parameter Format Type Meaning
#ERR-NUMBER (N4) I Error number to be retrieved.
#ERR-TEXT (A75) O Text, including substituted parameters.
#ERR-PARM (A75) I Parameters separated by (;). Formal parameters in the text must be specified as :n:, where n is the number of the parameter.

Note:
Error messages 9000 - 9999 are reserved for use by your site.

ISP-U003 - Read Data from Edit Session Program

This program can be used to read data from an edit session. When using this program, you must use the ISP-U03A data area which contains the following fields:

Parameter Format Type Meaning
#LINES (A132/20) O Data lines from the Editor session, a maximum of 20 lines can be read in one call.
#ED-SESNUM (B2) I Editor session number.
#ERROR-NUMBER (N4) O Error number, 0 if function was executed correctly.
#LINES-READ (N2) O Number of lines returned in field #LINES.
#LINES-TO-READ (N2) I/O Number of lines to read in 1 call
#LINE-LENGTH (N4) O Length of the lines.
#ED-NUM (N6) W Do not modify between calls.
#EOF (L) O True if the last lines have been read.
#TRACE (L) O If true, the number of lines, the information about the last line and the first 60 characters of each line read are displayed.

Example: 

DEFINE DATA
LOCAL USING ISP-U03A
LOCAL
1 #I    (N2)
END-DEFINE
INPUT #ED-SESNUM
*
MOVE 20 TO   #LINES-TO-READ
*
WRITE 'user processing of a macro result' //
*
REPEAT
  CALLNAT 'ISP-U003' #READ-PARM
  IF #ERROR-NUMBER NE 0
    WRITE '=' #ERROR-NUMBER
    ESCAPE BOTTOM
  END-IF
  FOR #I = 1 TO #LINES-READ
    PERFORM LINE-PROCESSING
  END-FOR
  IF #EOF
    ESCAPE BOTTOM
  END-IF
END-REPEAT
*
DEFINE SUBROUTINE LINE-PROCESSING
PRINT  #LINES(#I)
END-SUBROUTINE
END

ISP-U004 - Pass Command Script Program

This subprogram can be used to pass a command script (that is, a sequence of Natural ISPF commands) to Natural ISPF and to execute it when Natural ISPF is invoked next time. See also member ISP-COAP in the example library.

Parameter Format Type Meaning
#IN-COMMANDS (A50/10) I Command lines to be processed.
#IN-LINES (N2) I Number of lines to be processed in IN-COMMANDS.
#COMMAND-POS (A1)   For future use.
#FUNCTION (A1)   For future use.
#RC   O

Return code:

0 - Processing terminated ok.

1 - Natural ISPF is not active.

2 - Processing terminated with error.

ISP-U005 - Check for Natural Member Versions Program

Subprogram checks whether versions (update decks) for a Natural member exist.

Parameter Format Type Meaning
#IN-LIBRARY (A8) I Natural library name.
#IN-MEMBER (A8) I Natural member name.
#RC (N4) O

Return code:

0 - Processing terminated ok.

#OUT-VERSION (L) O TRUE Versions for this member exist.
#GEN-VERSION (L) O FALSE Natural ISPF versioning is not active in this environment.

ISP-U006 - Set Source Area Attributes Program

Subprogram sets source area attributes and is used in macro processing.

Parameter Format Type Meaning
#IN-MEMBER (A8) I Member name to be set.
#IN-TYPE (A1) I Natural object type to be set.
#IN-MODE (A1) I Programming mode (S/R) to be set.

ISP-U007 - Check User Authorization Program

This subprogram checks whether the current user is authorized to use Natural ISPF or certain parts of its functionality.

Parameter Format Type Meaning
#IN-OBJECT (A2) I 2-character code of Natural ISPF object being checked (leave blank to check if user is authorized to access any object).
#IN-FUNCTION (A2) I 2-character code of Natural ISPF object being checked (leave blank to check if user is authorized to use any function valid for a specific object; irrelevant if IN-OBJECT is blank).
#RC (N4) O

Return code:

0 - User is authorized.

-1 - User is not authorized.

>0 - "Error in execution". Use USR0320N to retrieve error text from library SYSISP1.

= -NNNN - Natural runtime error NNNN has occurred during execution. Use USR0120N to retrieve error text.

ISP-U008 - Current Session Program Including Global Data

This program is supplied in object form only. It is a Natural subprogram which returns information about the current Natural ISPF session and can be called from user programs outside Natural ISPF. It works like ISP-U000 but includes global data

The following parameters must be defined:

Parameter Format Type Meaning
#OBJECT (A2) O Contains 2-character abbreviation of the object type. For a list of possible values, see the Table of Exits and Object Abbreviations in the section User Exits in the Natural ISPF Administration Guide.
#FUNCTION (A2) O Contains 2-character abbreviation of the function currently being executed.
#CURR-SES-NUM (N2) O Contains session number of SAG edit session.
#L-COMMAND (A50) O Contains command line to be interpreted.
#MACRO-CHAR (A1) O Contains character which will be interpreted as macro character.
#CMD-DEL (A1) O Contains command delimiter character for command line.
#SES-DATA (A253) O Contains all parameters; must be redefined according to object type. A special local data area is delivered in source form for this redefinition

ISP-U009 – Current Session Program / Previous Session Program

This program is supplied in object form only. It is a Natural subprogram which returns information about the current Natural ISPF session and can be called from user programs outside Natural ISPF. It works in the same way as ISP-U000 except when executing a Natural program. In this case, the data of the previous session is returned.

The following parameters must be defined:

Parameter Format Type Meaning
#OBJECT (A2) O Contains 2-character abbreviation of the object type. For a list of possible values, see the Table of Exits and Object Abbreviations in section User Exits in the Natural ISPF Administration Guide.
#FUNCTION (A2) O Contains 2-character abbreviation of the function currently executed.
#SES-DATA (A253) O Contains all parameters; must be redefined according to object type. A special local data area is delivered in source form for this redefinition.