| API Routine: | APINSTFF |
This API lets obtain from the ACF a chunk of:
a Natural source,
a Natural loadable,
a foreign object (be it a source or a loadable),
a DDM,
a short error message (seen as a sequence of up to 60 lines, one per language),
long error messages (those of same number and different languages stringed one after another),
a USED list,
a USED BY list.
Note:
APINSTFF can be seen as APINNSRC expanded and corrected.
APINSTFF can be invoked with:
CALLNAT 'APINSTFF' API-PARM API-STFF-PARM
Set API-PARM.API-MAIN-FUNC to:
| D | To obtain a chunk. |
| S | If the chunk is to be one of a short error message.Otherwise leave it blank. |
A definition of API-STFF-PARM is provided in LDA UPILSTFF in library SYSPACUS.
This document covers the following topics:
| Field Name | Format | Description | |
|---|---|---|---|
| API-STFF-PARM | |||
| APPLICATION | A32 | in | |
| OBJECT | A32 | in | |
| VERSION | N4 | in/out | |
| TYPE | A6 | in/out | |
| TYPE1 | A1 | ||
| TYPE2 | A4 | ||
| TYPE3 | A1 | ||
| LINE-CNT | P5 | in/out | |
| OTHER-APPLICATION | A32 (1:10) 1* | out | |
| LINE | A250 (1:10) 1* | out | |
| API-PAC-AREA | A64 | in/out | |
1*: This is the proposed default value. Any value equal or greater 1 can be defined by the user.
Whenever APINSTFF is called API-STFF-PARM.APPLICATION should carry the name of the compartment of tha ACF holding the object and API-STFF-PARM.OBJECT should carry the name of the object.
API-STFF-PARM.VERSION may carry the version number of the object. If API-STFF-PARM.VERSION LE 0, then the highest numbered of the otherwise suitable is chosen; in this case the number of the chosen version is returned in API-STFF-PARM.VERSION.
[API-STFF-PARM.TYPE1] must be 'D' for DDM, 'E' for error message, 'F' for foreign, or 'N' for NATURAL.
The four possible settings of API-STFF-PARM.TYPE1 can be usefully combined with the following values of API-STFF-PARM.TYPE3:
| TYPE1 | TYPE3 |
|---|---|
| D | ' ' for the DDM as normally stored in an FDIC, |
| 'B' for the USED BY list. | |
| E | ' ' for the short or long error messages themselves, |
| 'B' for the USED BY list. | |
| F | 'S' for source, |
| 'L' for loadable. | |
| N | 'B' for the USED BY list, |
| 'L' for loadable, 'S' for source, 'U' for USED list. |
If [API-STFF-PARM.TYPE1] = 'F', then API-STFF-PARM.TYPE2 should carry the PAC foreign type code of the object with the leading '3' pared off (eg, '3JCL' would turn into 'JCL'). If [API-STFF-PARM.TYPE1] = 'N', then API-STFF-PARM.TYPE2 may carry the one character code of the NATURAL type of the object (eg, 'N' for subprogram or 'P' for program). If [API-STFF-PARM.TYPE1] = 'N' and [API-STFF-PARM.TYPE2] = ' ' and an suitable versioned object is found, then its Natural type code is returned in API-STFF-PARM.TYPE2.
[API-STFF-PARM.LINE-CNT] is made 0, if negative; it is made 10, if greater than 10. It is then interpreted as the number of lines (the size of the chunk) to be returned. In particular, no lines will be returned, if LINE-CNT = 0. APINSTFF returns in API-STFF-PARM.LINE-CNT the number of lines of the returned chunk. It may be less than the adjusted original value, if the end of the DDM, loadable, source, USED list, or USED BY list has been reached.
API-STFF-PARM.LINE will carry the returned chunk.
API-STFF-PARM.OTHER-APPLICATION will be used if [API-STFF-PARM.TYPE3] is 'B' or 'U'. In this case API-STFF-PARM.OTHER-APPLICATION(I) will normally carry the name of the compartment holding the object referred to in API-STFF-PARM.LINE(I) for any I in {1,...,[API-STFF-PARM.LINE-CNT]}. A list can contain a non-object-reference line or a dead reference line; an API-STFF-PARM.OTHER-APPLICATION(I) may carry a compartment name if API-STFF-PARM.LINE(I) does not carry an object reference and it will be empty if [API-STFF-PARM.LINE(I)] is a dead reference.
Normally, API-STFF-PARM.API-PAC-AREA should be reset when the first chunk of a DDM, loadable, source, USED list, or USED BY list is wanted. API-STFF-PARM.API-PAC-AREA should be left untouched for a next call to obtain an immediately following chunk of the same DDM, loadable, source, USED list, or USED BY list. Set the last three bytes of API-STFF-PARM.API-PAC-AREA to H'F0F0F1' if the directory lines of the object are not to be skipped (otherwise they are skipped).
APINSTFF returns the following [API-PARM.API-MSG-NO]:
| 0000 | if an object has been found and a non-final chunk is being returned. |
| 1011 | if the specified [API-PARM.API-MAIN-FUNC] is meaningless (ie, is not 'D'). |
| 6448 | if [API-STFF-PARM.TYPE1] is meaningless (ie, is not 'D', 'E', 'F', or 'N'). |
| 6531 | if the combination of [API-STFF-PARM.TYPE1] and [API-STFF-PARM.TYPE3] is inadmissible. |
| 7205 | if the "initialisation" has failed, ie, logical files 210 and 211 have not been found set at a pair of matching ACF and PCF. |
| 7251 | if the application has not been found or no object has been found. |
| 9999 | if an object has been found and a final chunk is being returned. |
Other values of API-PARM.API-MSG-NO may be received in more unusual situations.