This document covers the following topics:
The records stored by ASF can be read by a Natural application program via a defined programming interface called the Application Programming Interface (API). The ASF API consists of a single, very powerful subprogram named ASFGET01.
ASFGET01 is distributed with the ASF package and is called via the Natural statement CALLNAT. The input parameters required by ASFGET01 are the record selection criteria known from the ASF evaluations and the names of the required ASF data fields. The output parameters returned by ASFGET01 are the required ASF data fields from the specified records.
If the ASFGET01 output buffer is not large enough to return data for all of the records that meet the selection criteria, the subprogram can be called repeatedly until all of the records have been processed.
To illustrate the use of ASFGET01 in an application program, the sample programs PEXAMPL1 and PEXAMPL2 are supplied with the ASF package. You can display the output of these two programs by selecting the service codes "1" and "2" in the ASF Utilities and Services Menu.
To allow you to familiarize yourself with ASFGET01, ASF includes an interface which allows you to pass parameters online to ASFGET01 and to view the results of the ASFGET01 calls directly on the screen. You can access this interface by selecting the service code "I" in the ASF Utilities and Services Menu.
The first time ASFGET01 is called, you must set the field FKTCODE to "00". Also, each time before you change the search criteria you must call ASFGET01 with FKTCODE set to "00". This causes ASFGET01 to initialize its search processing. For this initialization call, only FKTCODE needs to be set; all other ASFGET01 parameters can be left blank.
After you have initialized ASFGET01, you can call ASFGET01 with FKTCODE set to "01" or "02", depending on the order in which you want to retrieve the records. You specify the search criteria for the records that you want to retrieve in the field SELECTION-CRITERIA.
For FKTCODE "01", ASF sorts the records in the sequence date/time, database ID, file ID. ASF returns the data of all databases and files within the given time frame. The database and file ID specified are used to establish a starting and an ending point. Nevertheless in most cases the first DB/file values returned are the lowest possible values and not the specified ones. This is because ASF stores the time internally more precisely than the units of minutes offered by the API. This means the time value returned is already higher than the specified time and the start values of the DB/file are meaningless. If you use the "±nnnnR" (relative records) notation for the date, the returned values start always with given DB/file values. This is because in this case ASF uses the exact internal time stamp for establishing the starting position. See the section Absolute and Relative Date Format for more information on specifying date formats.
For FKTCODE "02", ASF sorts the records in the sequence database ID, file ID, date/time. ASF returns the data of the given database and file for the time frame specified.
ASFGET01 returns only selected ASF data fields from records which meet your search criteria. You supply the names of the required ASF data fields in the field FIELD-NAMES. You must specify the name of at least one ASF data field; the maximum number of names that you can specify is 150. Corresponding to each ASF data field in FIELD-NAMES you can specify a unit of measurement in UNITS. ASFGET01 returns the value of the ASF data field in the given unit of measurement. If you do not specify a unit of measurement for a given ASF data field, the default unit of measurement is used.
For each record which satisfies the search criteria, ASFGET01 returns one or more ASF data fields from the record (according to the data you specify in FIELD-NAMES) and a special key field. The number of records which can be processed by a single ASFGET01 call depends on the number of ASF data fields which you specify in FIELD-NAMES. A single call of ASFGET01 can return data for 150 ASF data fields, so the number of records which can be processed by a single ASFGET01 call is given by the formula
150 / (number of required ASF fields per record+1 key field).
ASFGET01 processes only whole records, so if there is insufficient space left for another record in the output buffer (all requested ASF data fields plus the special key field), the remaining portion of the buffer is left blank.
Example 1
If 2 ASF data fields are to be returned from each record that satisfies the search criteria, the ASFGET01 buffer can contain values for
150 / (2 ASF data fields+1 key field) = 50 records.
Example 2
If 39 ASF data fields are to be returned from each record that satisfies the search criteria, then
150/(39 ASF data fields+1 key field) = 3 complete records
can be processed per ASFGET01 call. Since 3 records require
3*(39+1) = 120 elements,
the remaining 30 elements will be blank.
If a single call of ASFGET01 is not sufficient to process all of the records which meet the search criteria, ASFGET01 processes as many records as it can for the current call, and then sets RETURNCODE to 0 and ASF-MSG-NR to 507. ASFGET01 stores restart information in the field WORK. To process the next records in the search sequence, you must call ASFGET01 again with unchanged input parameters; in particular, you must not change the contents of the field WORK.
If WORK is blank upon completion of the current ASFGET01 call and RETURNCODE is 0, then the records returned in the current ASFGET01 buffer are the last records which satisfy the search criteria. In this case, the field ASF-MSG-NR contains the value 505.
If #TRACE contains the value "TRACE", the ASF trace facility is started. All trace types are activated in this case. The ASF Trace Facility is described in the section Tracing ASF. The #TRACE parameter is optional. If it is omitted when ASFGET01 is called, the trace is not activated.
The call of ASFGET01 in a Natural module has the format
CALLNAT 'ASFGET01' #FUNCTION-CODE
#INPUT-PARAMETERS
#OUTPUT-PARAMETERS
#RETURN
#WORK
#TRACE /* optional |
The parameters of the ASFGET01 call are defined as follows:
1 #FUNCTION-CODE (A2)
1 #INPUT-PARAMETERS
2 #SELECTION-CRITERIA (A67)
2 REDEFINE #SELECTION-CRITERIA
3 #FROM-DATE (A10)
3 #FROM-TIME (A5)
3 #TO-DATE (A10)
3 #TO-TIME (A5)
3 #DATE-FORMAT-CODE (A1)
3 #STORE-PROFILE (A16)
3 #STORE-PROFILE-ID (A5)
3 #STORE-TYPE (A2)
3 #ORIGIN (A3)
3 #DB (A5)
3 #FILE (A5)
2 #FORMAT (A4)
2 REDEFINE #FORMAT
3 #DECIMAL-SIGN (A1)
3 #THOUSAND-SIGN (A1)
3 #KILO-TRANSFORMATION (A1)
3 #MEGA-TRANSFORMATION (A1)
2 #NR-RECORDS (N3)
2 #FIELD-NAMES (A16/1:150)
2 #UNITS (A2/1:150)
2 #RESERVE (A30)
1 #OUTPUT-PARAMETERS
2 #FIELD-DATA (A18/1:150)
2 #ADDITIONS1 (A250)
2 #ADDITIONS2 (A250)
1 #RETURN
2 #RETURNCODE (N2)
2 #ASF-MSG-NR (N4)
2 #ASF-MSG (A60)
2 #WRONG-VALUE (A32)
2 #PARAM-NO (N3)
1 #WORK (A114)
1 #TRACE (A5) BY VALUE OPTIONAL
The parameters are described in detail on the following pages.
1 #FUNCTION-CODE (A2)
The following values are valid for this field:
| 00 | Initialize ASFGET01. |
| 01 |
ASFGET01 returns records in the sorting sequence date/time, database ID, file ID (TDF). The number of records returned for each ASFGET01 call is limited physically by the size of the ASFGET01 buffer and logically by the value supplied in the NR-RECORDS field. The search key for the starting record is composed of the fields STORE-TYPE, STORE-PROFIL-ID, FROM-DATE, DB, FILE. The key for the last record required is composed of the fields STORE-TYPE, STORE-PROFIL-ID, TO-DATE, DB, FILE. If TO-DATE is blank, the search continues to the end of the file. |
| 02 | ASFGET01 returns records in the sorting sequence database ID, file ID, date/time (DFT). The number of records returned for each ASFGET01 call is limited physically by the size of the ASFGET01 buffer and logically by the value supplied for the NR-RECORDS field. The search key is composed of the fields STORE-TYPE, STORE-PROFIL-ID, DB, FILE, FROM-DATE. The key for the last record required is composed of the fields STORE-TYPE, STORE-PROFIL-ID, DB, FILE, TO-DATE. If TO-DATE is blank, the search continues to the end of the file. |
1 #INPUT-PARAMETERS
2 #SELECTION-CRITERIA (A67)
2 REDEFINE #SELECTION-CRITERIA
3 #FROM-DATE (A10)
3 #FROM-TIME (A5)
3 #TO-DATE (A10)
3 #TO-TIME (A5)
3 #DATE-FORMAT-CODE (A1)
3 #STORE-PROFILE (A16)
3 #STORE-PROFILE-ID (A5)
3 #STORE-TYPE (A2)
3 #ORIGIN (A3)
3 #DB (A5)
3 #FILE (A5)
2 #FORMAT (A4)
2 REDEFINE #FORMAT
3 #DECIMAL-SIGN (A1)
3 #THOUSAND-SIGN (A1)
3 #KILO-TRANSFORMATION (A1)
3 #MEGA-TRANSFORMATION (A1)
2 #NR-RECORDS (N3)
2 #FIELD-NAMES (A16/1:150)
2 #UNITS (A2/1:150)
2 #RESERVE (A30)
These fields specify the start and end dates and times for the search. The fields FROM-DATE and TO-DATE must be in the format indicated by the DATE-FORMAT-CODE field. The fields FROM-TIME and TO-TIME can be left blank; the default for FROM-TIME is 00:00 and the default for TO-TIME is 23:59.
This field specifies the format of the input and output date fields. The following values are allowed:
| 1 | Format YYYY-MM-DD |
| 2 | Format DD.MM.YYYY |
The STORE-PROFIL field specifies the name of the Store Profile which was used to store the original ASF records.
The field STORE-PROFIL-ID specifies the internal ID of the Store Profile.
At least one of these fields must be specified. If both are specified, ASFGET01 uses the value in STORE-PROFIL-ID.
ASFGET01 uses the value in this field as a starting value for the search. The value specified does not have to correspond to any of the Store Types actually used - it merely specifies a start value for the search.
The value specified in this field determines whether nucleus records, trend records or both are returned. The valid values are:
| NU | nucleus records only. |
| TR | trend records only. |
| ALL | both nucleus and trend records. |
If this field is left blank, both nucleus and trend records will be returned.
DB and FILE specify the starting values for the database ID and file number to be used in the search.
If neither of these fields is specified, ASFGET01 uses the starting values DB=1 and FILE=1. If only DB is specified, ASFGET01 uses the starting value FILE=1. If FILE is specified, DB must also be specified.
These optional fields correspond to the fields "Decimal character", "Separating sign", "Kilo if > 1000" and "Mega if > 1000K" respectively in the ASF User Profile. Refer to Define User Profile in the section The Menu System for further details.
If you specify values for these fields, numerical data returned by ASFGET01 will be formatted accordingly. This is useful if you want to output the numerical data to a screen or a printer. If, however, you want to use one or more of the numerical values in a subsequent calculation in your application program, they must not be formatted, so you should leave these fields blank.
This field specifies the maximum number of records to be returned per ASFGET01 call, provided that the ASFGET01 buffer is sufficiently large to contain this number of records. If no value is specified for this field, ASFGET01 returns as many records as possible in the ASFGET01 buffer.
Note that there is no way to specify explicitly the total number of records to be returned for a given set of search criteria. The total number of records that will be returned is always determined implicitly by the search criteria.
The field FIELD-NAMES specifies the names of the ASF data fields which are to be retrieved from the records which meet the search criteria. The field UNITS specifies the units of measurement (for example "BL" for blocks) to be used for the retrieved ASF data fields.
Both FIELD-NAMES and UNITS are arrays of dimension 150, so up to 149 ASF data fields per stored record in the ASF database plus 1 key field can be returned for each ASFGET01 call.
The list of names in FIELD-NAMES is terminated by the first blank value or if 150 ASF data fields are specified. If a value in UNITS is blank, the default unit of measurement will be used for the corresponding ASF data field.
The values that are returned by the ASFGET01 call are stored in the field FIELD-DATA.
The available field names and units are listed in the section ASF Group and Field Names in the ASF Examples documentation. .
This field is currently unused.
1 #OUTPUT-PARAMETERS 2 #FIELD-DATA (A18/1:150) 2 #ADDITIONS1 (A250) 2 #ADDITIONS2 (A250)
ASF data fields for the records which meet the search criteria are returned in this field. The names of the ASF data fields are specified in the field FIELD-NAMES. For each record, an additional key field is returned, whose format depends on the value specified for FKT-CODE.
If FKT-CODE="01", the key field can be redefined as follows:
Store Type (A2) Store Profile ID (P5) Date/Time (T) Database ID (P5) File ID (P5)
If FKT-CODE="02", the key field can be redefined as follows:
Store Type (A2) Store Profile ID (P5) Database ID (P5) File ID (P5) Date/Time (T)
FIELD-DATA is an array of dimension 150, so up to 149 ASF data fields plus the key field can be returned per record for each ASFGET01 call.
Using the notation FIELD-DATA(n) to represent the nth element in FIELD-DATA, the key field is returned in FIELD-DATA(1), the first ASF data field is returned in FIELD-DATA(2), the second ASF data field in FIELD-DATA(3) etc. This means that, because of the additional key field, the unit of measurement for the value returned in FIELD-DATA(n) is specified in UNITS(n-1).
If a given element FIELD-DATA(n) is filled with question marks ("???...?"), the corresponding name in FIELD-NAMES(n-1) was invalid.
These fields are currently unused.
1 #RETURN 2 #RETURNCODE (N2) 2 #ASF-MSG-NR (N4) 2 #ASF-MSG (A60) 2 #WRONG-VALUE (A32) 2 #PARAM-NO (N3)
The value in RETURNCODE indicates whether the ASFGET01 call was successful. If the value 0 is returned, the call was successful. If the value 1 is returned, an error was detected by ASFGET01.
Further information on the completion status is provided in the fields ASF-MSG-NR and ASF-MSG. The relationship between these two fields and RETURNCODE is shown in the following table:
| RETURNCODE | ASF-MSG-NR | ASF-MSG |
|---|---|---|
| 0 | 504 | Initialization of ASFGET01 completed successfully. |
| 0 | 505 | End of records reached. |
| 0 | 507 | Not all of the records found could be displayed. |
| 0 | 508 | Work field has been modified. |
| 1 | 501 | Invalid function code. |
| 1 | 506 | Too many records/ASF data fields requested for a single ASFGET01 call. |
| 1 | 509 | Field must be numeric. The contents of the incorrect input field are returned in WRONG-VALUE, and the number of the incorrect field is returned in PARAM-NO. |
If RETURNCODE is not 0 and the error was caused by incorrectly specifying an input field for the ASFGET01 call, the field WRONG-VALUE contains the content of the input field and the field PARAM-NO contains the number of the incorrect input field (FKTCODE=1, FROM-DATE=2 etc.).
1 #WORK (A114)
This field is used as working storage by ASFGET01 and must not be modified by the user. It stores information concerning the last record processed, in cases where a single call of ASFGET01 is not sufficient to process all the records which satisfy the search criteria. If ASFGET01 is called again with unchanged input fields, the next records satisfying the search criteria are returned.
If WORK is blank upon completion of the current ASFGET01 call and RETURNCODE is 0, then the records returned in the current ASFGET01 buffer are the last records which satisfy the search criteria. In this case, the field ASF-MSG-NR will contain the value 505.
Note:
When ASFGET01 is called with #FUNCTION-CODE set to
"00", WORK is set to blanks.
1 #TRACE (A5) BY VALUE OPTIONAL
If this parameter is specified and contains the value "TRACE", all ASF internal trace types are activated.
If it contains the value "PROG", the ASF program trace is activated.