CA Ramis User Functions RAMSTIND and RAMSUBST
Article ID: 56221
Updated On:
Products
Issue/Introduction
Locating a Substring: RAMSTIND Function
The user function RAMSTIND can be used to locate a substring within an alphanumeric character string in a field or variable. If the substring exists, RAMSTIND returns the position of the first character in the first occurrence of the substring within the source value. If the substring does not exist, RAMSTIND returns the value zero (0).
Environment
Release: 7.4
CA RAMIS
CA RAMIS Reporter
Resolution
The syntax for invoking the RAMSTIND function in a DEFINE, COMPUTE, or SBX activity is described below.
Notice that three fields must be defined. The first two fields, stringlengthname and sourcelengthname, contain length values. In the new-fieldname definition, the length fieldnames, not the length values, are specified in the argument list passed to the function.
SYNTAX
stringlengthname/I4 = n;
sourcelengthname/I4 = n;
new-fieldname/I4 = RAMSTIND(string, stringlengthname,
source-name, sourcelengthname);
|
stringlengthname |
Specifies an integer (I) type field that contains the length (n) of the substring to be located. |
|
sourcelengthname |
Specifies an integer (I) type field that contains the maximum length (n) of source field values. |
|
new-fieldname/I4 |
Specifies the integer field that will contain the extracted substring location. The type must be integer (I) and the length (4) must match the length specified with the FUNCTION command (see "Identifying the Functions" below). |
|
string |
Specifies the substring to be located in values of the source field. |
|
source-name |
Specifies the name of a CA-Ramis file field, defined field, or variable. Values of this field or variable will be searched for the specified substring. The field or variable must be alphanumeric (A). |
Extracting a Substring: RAMSUBST Function
The user function RAMSUBST can be used to extract a substring from an alphanumeric character string contained in a CA-Ramis field or variable.
The syntax for invoking the RAMSUBST function in a DEFINE, COMPUTE, or SBX activity is described below.
Notice that four fields must be defined. The first three fields, sourcelengthname, positionname, and stringlengthname, contain length and position values. In the new-fieldname definition, the length and position fieldnames, not their values, are specified in the argument list passed to the function.
SYNTAX
sourcelengthname/I4 = n;
positionname/I4 = n;
stringlengthname/I4 = n;
new-fieldname/An = RAMSUBST(source-name, sourcelengthname,
positionname, stringlengthname);
| sourcelengthname | Specifies an integer (I) type field that contains the maximum length (n) of source field values. |
|
positionname |
Specifies an integer (I) type field that contains the position (n) in the source field of the first character of the substring to be extracted. |
|
stringlengthname |
Specifies an integer (I) type field that contains the length (n) of the substring. |
|
new-fieldname/An |
Specifies the field that will contain the extracted substring. The type must be alphanumeric (A) and the length (n) must match the length specified with the FUNCTION command (see "Identifying the Functions" below). |
|
source-name |
Specifies the CA-Ramis file field, defined field, or variable. The substring will be extracted from values of this field. The field or variable must be alphanumeric (A). |
Identifying the Functions
Before any user function can be invoked, the function or functions must be identified with the command FUNCTION ADD. If desired, the QUERY FUNCTION can be issued to list the functions identified in the current Ramis session.
FUNCTION ADD
RAMSTIND/I4;
RAMSUBST/An;
END
(where "n" is the length of the longest substring to be extracted,
up to a maximum of 130 characters)
After the FUNCTION command is issued, the user can invoke both RAMSTIND and RAMSUBST functions in any DEFINE, COMPUTE, or SBX activity for the remainder of the CA-Ramis session.
Note: If the user function was not previously defined with the FUNCTION command, the following error will occur:
DF0403: FIELDNAME or operation functionname not recognized
String Function Example: Locating and Extracting First and Last Names
The below example shows how to identify the RAMSTIND and RAMSUBST functions to CA-Ramis and how to invoke the functions in a DEFINE set. This will extract the first and last names from the SALESPERSON field in the sample SALESTAFF file.
(Note: The character string stored in the SALESPERSON field contains the last name, followed by a comma and a blank space, followed by the first name. For example: REID, SUSAN)
Invoking the RAMSTIND and RAMSUBST Functions
FUNCTION ADD
RAMSTIND/I4;
RAMSUBST/A25;
END
QUERY FUNCTION
? will display?
FUNCTION TYPE LENGTH
RAMSTIND I 4
RAMSUBST A 25
The below source code demonstrates how a DEFINE set in are porting activity can invoke the functions to extract the first name from the SALESPERSON field.
DEFINE
FILE SALESTAFF
SOURCELN/I4 = 25;
STRINGLN/I4 = 1;
COM/I4 = RAMSTIND(',',STRINGLN,SALESPERSON,SOURCELN);
INIT/I4 = COM + 2;
SUBLENGTH/I4 = IF COM NE 0 THEN (SOURCELN - (COM + STRINGLN))ELSE 0;
FIRSTNAME/A25 = RAMSUBST(SALESPERSON,SOURCELN,INIT,SUBLENGTH);
START/I4 = 1;
END/I4 = COM-1;
LASTNAME/A25 = RAMSUBST(SALESPERSON,SOURCELN,START,END);
END
TABLE
' Salesperson COM INIT SUBLENGTH '
' Firstname '
' Lastname '
' ----------- --- ---- --------- '
FILE SALESTAFF
PRINT SALESPERSON AS ' '
OVER FIRSTNAME AS ' ' OVER LASTNAME AS ' '
AND COM AS ' ' AND INIT AS ' ' AND SUBLENGTH AS ' ' END
Source Code Comments
To extract the first name, both RAMSTIND and RAMSUBST are invoked. The RAMSTIND function returns the position of the comma to the COM field. To calculate the position of the first character in the first name, an intermediate field, INIT, adds 2 to the COM value. The INIT value is passed as the position argument to the RAMSUBST function, which returns the substring that contains the first name.
The SUBLENGTH field calculates the length of the substring that contains the first name. The calculation adds the constant value 1 (in this case previously defined with STRINGLN) to the comma position value (COM), and subtracts the result from the source field length (SOURCELN). Keep in mind that a defined field must be used to pass a constant value to a user function.
To obtain the last name, the ending position is calculated by subtracting 2 from COM with a starting position of 1.
Sample Output
The DEFINE and TABLE request above will produce the following CA-Ramis report against the sample SALESTAFF file.
Salesperson COM INIT SUBLENGTH
Firstname
Lastname
----------- --- ---- ---------
BECKER, SAM 7 9 17
SAM
BECKER
JOHNSON, WALTER 8 10 16
WALTER
JOHNSON
REID, SUSAN 5 7 19
SUSAN
REID
YOUNG, LEE 6 8 18
LEE
YOUNG
PEREZ, EVAN 6 8 18
EVAN
PEREZ
WEISS, ASTRID 6 8 18
ASTRID
WEISS
Unloading the Function or Functions
Normally, a user function is loaded at the start of the activity in which it is invoked and is unloaded at the end of that activity. Notice that in the case of an SBX procedure, the entire procedure is considered the activity. If it is desirable to free dynamic memory before an SBX activity ends, any function can be unloaded with the FUNCTION UNLOAD command.
FUNCTION UNLOAD
RAMSTIND
RAMSUBST
END
Other Ways To Locate a Substring or To Extract a Character String
- In an SBX procedure, it is recommended that the supplied SBX functions, %LLOCATE and %RLOCATE, be used to locate a character string.
- In a DEFINE or COMPUTE set, the supplied Ramis function, EDIT, can be used with a mask to extract a character string.
- In an SBX procedure, it is recommended that the supplied SBX function, %SUBST, be used to extract a character string.
Additional Information
For more information on user functions, DEFINE, TABLE, EDIT and other reporting capabilities, refer to the publication Syntax Based Reporting.
For more information on SBX and its functions, refer to the publication System Building Executive (SBX).
The CA Ramis Version 7.4 set of documentation can be found at CA Ramis Bookshelves and PDFs.
Feedback
