Field value manipulation

In the CARLa language, several functions for field manipulation are available. You specify these functions with a function name followed by the base field name and function-specific parameters, for example:

SUBSTRING(field,startpos,length)

You can nest functions to create advanced expressions. For example, suppose a field value is divided into three parts by semicolons, and the third part contains a price and a comment in any order. You can use the following combination of the PARSE and WORD functions to obtain the price:

PARSE(WORD(field,3,’;’),’$’,’ ’)

Taking just the number that follows the $ sign and handling it as an integer can be done with this combination:

CONVERT(PARSE(WORD(field,3,’;’),’$’,’.’),DECIMAL)

You can also use character fields as the basis for an indirect reference. Suppose in the same example that the second part of the field value contains a user ID. The following might be used to obtain an email address:

WORD(field,2,’;’):EMAIL.USER.ADDRESS

Indirect references are described in section Indirect reference or lookup. The following functions are available in the CARLa language:

CONVERT
Normal CARLa processing interprets the values in a field according to the input format that is associated with its field type. For example, fields defined via SMF_FIELD in report type SMF, or based on the RECORD field in report types that are defined via DEFTYPE, have the output format ASIS and are processed as character strings. However, sometimes it is useful to process the data in a different manner. For example, a record might contain a date format that you want to convert to another type of date format, or you might want to convert a human-readable date and time string to an internal date for processing. The product provides the CONVERT function for this purpose.

The CONVERT function has the following syntax:

CONVERT(field, input format [, internal format])

The input format specifies how to interpret the input values. The internal format specifies to the program how to handle the data internally for selection and sorting purposes. The latter also implies a default output format.

The following input formats are available for processing date and time stamps. The supported format for date values can be found in Date fields.
DATETIME
With this input format, the date and the time parts of the string are in a printable form, such as 11 Nov 2019 13:10:00. Any input following the date and time is ignored. The default internal format is DATETIME. The time is expected in the following format: [h]h:[m]m:ss[:cc]. Instead of the colon (:), any single non-space, non-digit separator can be used.
INTERNALDATETIME
This input format reads the zSecure internal representation of the date and time. You can use this format to convert standard date and time fields for use with other output formats. The default internal format is SMFTIME. For example:
def type=svc mth("Mth",month,3) as convert(collect_datetime,internaldatetime,SMFTIMESTAMP)
SMFTIMESTAMP
This input format reads the full time stamp as found in SMF records (a 4-byte centi-seconds value followed by a 4-byte date x'ccyydddF' where cc is the century so that 0=19xx). The default internal format is DATETIME.
The following example shows how to read the time and date when SMF data loss started from the fields SMF7STM and SMF7STD:
newlist type=smf  title='SMF data loss stop and start'
  s type=7
  define SMF7STMSTD(datetime,16) as convert(smf_field(20,8),smftimestamp)
  sortlist date time SMF7STMSTD recorddesc
TOD
This input format reads an 8 or 16-byte (binary) time of day (TOD) clock format timestamp. There is no support to assign or add a time zone from a system. If the input length is not 8 or 16 bytes, no values are returned. The supported date furthest into the future is 9999-12-31 (31 December 9999). The default internal format is DATETIME.
The following internal formats are available to convert date and time stamps to:
DATE
The date part of the field. A value in this format field can be printed with the output formats ACF2DATE, DATE (default), JULDATE, USDATE, $DATE.
DATETIME
This is the standard internal format for data and time in centi-second accuracy. It can be printed with most date and time formats.
SMFTIME
The time part of the field. This internal format can be printed with the SMFTIME output format only.
SMFTIMESTAMP
The date and time can be printed with the SMF time stamp format.
WEEKDAY
The day of the week. This internal format can be printed with the WEEKDAY output format, or as a decimal number using DEC or NUM..
The following list contains the other available input formats:
DECIMAL
This input format reads a human readable decimal integer, containing no commas or dots. The default internal format is DECIMAL, which is a standard numeric field that can be printed with the output formats DEC (default), DEC$BLANK, DEC$NO, and NUM.
IPSTR
This input format reads a human-readable IP address. The default internal format is IP and no other conversions are allowed. This internal format can be printed with the output formats IP, IPSQ, IPV4OR6, and IPV4OR6SQ.
PACKED
This input format reads a packed decimal field as defined in the IBM z/Architecture Principles of Operation. The default internal format is DECIMAL which is a standard numeric field. This internal format can be printed with the output formats DEC (default), DEC$BLANK, DEC$NO, and NUM.
EXTRACTDN
An entity associated to a digital certificate, such as the issuer of the certificate or the subject of the certificate, is expressed as a Distinguished Name. In particular, fields such as CERTIFICATE_SUBJECT and CERTIFICATE_ISSUER_FULL of TYPE=RACF are based on a Distinguished Name. The full Distinguished Name consists of a sequence of relative distinguished names. That is to say, it is qualified on a number of levels, such as the Country level (for example, C=US). The EXTRACTDN function can be used to extract a particular level from the Distinguished Name to display it separately. It has the following syntax: 
EXTRACTDN(field, level)
The field specified must be a BER-encoded Distinguished Name. The level selected must be one of the following:
Table 1. EXTRACTDN short names and long names
Short Name Long Name Example
C Country C=NL
SP State, Province SP=NY
L Location L=Internet
O Owner O=IBM
OU Org_unit OU=Security Systems Development
CN CommonName CN=Joe Smith
T Title T=Manager
DC Domain_Component DC=mydomain

The result returned by the EXTRACTDN function is a character string; for example, NL. The input value must be a BER-encoded Distinguished Name; that is, the primary command FIELDS should show the output format for the field as X.509-DN. Note that some other CARLa fields contain Distinguished Names in character format; for example, BINDDN.

The result of the EXTRACTDN function has the "repeated" property; for example, several levels of the organizational unit can be present. With the output in display format, the result has the MORE property by default; that is, it will be displayed on both the profile and profile details displays. The former shows "more" when multiple values are present.

LASTQUAL
Refers to the last qualifier in a field value. If the field value is aaa.bbb.ccc, the last qualifier is ccc. The syntax is LASTQUAL(field), where field is the field name.
PARSE
A particular section of a field, recognizable by unique identifiers before and after it, can be found with the PARSE operation. It has the following syntax: 
PARSE(field, [start separator][, end separator])
The field specified must have a character format. The start separator is the text right before the section wanted. The end separator is the text after the section wanted. For example, assume a field named DATA containing several items of information about a person: the name, function, and department. It is structured as follows: 
Name: Doe, J.; Function: programmer; Dept: Data Processing;
or 
Function: programmer; Dept: Data Processing; Name: Doe, J.;
PARSE(DATA,'Name: ',';')

will contain Doe, J.

Note:
  1. At least one of the separators must be specified.
  2. If the start separator is not specified, the start of the character string bounds the value returned. If the start separator is specified but not found, the result is missing. If a start separator occurs more than once, the first occurrence is used to calculate the field value to be returned.
  3. If the end separator is either not specified or specified but not found, the end of the character string bounds the value returned. If the end separator occurs more than once, the first occurrence (after a specified start separator) is used to calculate the field value to be returned.
PICT
Defines the character type of each character in the field value. The maximum supported field value length is 256 characters. The function returns a character string where each character represents the character type in the original field value. The possible types are:
  • @ - represents an alphabetic character (A-Z, a-z)
  • # - represents a number character ((0-9)
  • $ - represents a punctuation character
  • <space> represents a space character
  • .(dot) represents all other characters
QUALIF
An index number from 1 to 123 that represents a qualifier segment of a field value. The syntax is QUALIF(field,index).
field
The field name.
index
A number that represents the position of the qualifier segment in the name. If the field value is aaa.bbb.ccc, the index number 1 represents aaa.
QUALNUM
Calculates the number of qualifiers in the field value. The syntax is QUALNUM(field).
SUBSTRING, SUBSTR
Substrings can be generated from character fields using the SUBSTRING operation. The substring can have the following following formats:
  • SUBSTRING(field,startpos,length)
  • SUBSTRING(field,startpos:endpos)
  • SUBSTRING(field,startpos)

The field specified must have a character format. The startpos is the start position where the substring of the field may start; the first character in the field has position 1. You can specify a length or an endpos. If you specify a length, it must be at least 1. If you specify an endpos, it must be equal to, or greater than, the startpos. If neither length or endpos are specified, the substring continues until the end of the field.

For example, consider a site that has defined the user IDs in the format DDGGNN, where DD is the department, GG the workgroup, and NN the user number in the group. The department can be specified as either SUBSTRING(USER,1,2) or SUBSTRING(USER,1:2). The group can be specified as SUBSTRING(USER,3,2) (using a length) or SUBSTRING(USER,3:4) (using an endpos).

On an ISPF display, variables defined as substrings with an output format of CHAR or ASIS are modifiable if the source field was modifiable. Multiple substrings may be on the display at the same time. They may even overlap, but any actual updates may not conflict with any of the other places on the screen where the same information is being displayed. Multiple substrings of one repeat group field may only be present on the same line of the detail display.

WORD
A particular word can be found in a character field with the WORD operation. This has the following syntax: 
   WORD(field,number[,delimiter(s)])

The field specified must have a character format. The number is the number of the word wanted (that is, the second word in the sentence for number=2). The delimiter can be a single character, possibly between quotation marks (necessary if you want to specify a comma or another type of quotation mark), or a string of up to 40 characters. Each occurrence of (one of the) character(s) you specified will indicate the start of the next word in the sentence. If you omit the delimiter, the words are separated by one or more blanks and blanks occurring at the start of the record will be skipped. When a delimiter is followed immediately by a quotation mark (either single, left or back quotation mark), the scan will first search for the balancing quotation mark and only the first delimiter thereafter will start the next word. If that delimiter immediately follows the balancing quotation mark (for example, the result is a properly quoted string without further suffix), the quotation marks are stripped off. Otherwise, the quotation marks are left in place.

Some examples:

WORD(field,n) returns the nth blank delimited word, so: 
   field = "    one two   three 'four and five'"
results in: 
   WORD(field,1) = "one"
   WORD(field,2) = "two"
   WORD(field,3) = "three"
   WORD(field,4) = "four and five"
   WORD(field,5) = ""
WORD(field,n,delimiter) returns the nth token from the text string, where each occurrence of the delimiter signals the end of a token, so: 
   field = ";;one two; three;'four;five' "
results in: 
   WORD(field,1,';') = ""
   WORD(field,2,';') = ""
   WORD(field,3,';') = "one two"
   WORD(field,4,';') = " three"
   WORD(field,5,';') = "four;five"
   WORD(field,6,';') = ""