VSI Pascal supplies predeclared routines that manipulate character strings.
1 – BIN
The BIN function returns a character-string value that is the
binary equivalent of the specified parameter. The return value
is compatible with all other string types.
Syntax:
BIN( x [[, length[[, digits]]]] )
The parameter 'x' is the expression to be converted. This
parameter must have a size that is known at compile time; it
cannot be VARYING OF CHAR, a conformant parameter, or a schema
type.
Two optional integer parameters specify the length of the
resulting string and the minimum number of significant digits to
be returned. If you specify a length that is too short to hold
the converted value, the resulting string is truncated on the
left.
If you omit the optional parameters, the bit width of the
converted parameter value determines the string length and the
number of significant digits. By default, the number of
significant digits is the minimum number of characters necessary
to express all the bits of the converted parameter. This
default length is one character more than the default number of
digits, which causes a leading blank to be included in the
resulting string when both parameters are omitted.
2 – DEC
The DEC function returns character-string value that is the
decimal equivalent of the specified parameter. The return value
is compatible with all other string types.
Syntax:
DEC( x [[, length[[, digits]]]] )
The parameter 'x' is the expression to be converted. The DEC
function can take a parameter of any type except VARYING OF
CHAR, conformant parameters, or schema types. The DEC function
requires the size of 'x' to be less than or equal to the size of
INTEGER64 (if supported), or less than or equal to the size of
INTEGER32.
Two optional integer parameters specify the length of the
resulting string and the minimum number of significant digits to
be returned. If you specify a length that is too short to hold
the converted value, the resulting string is truncated on the
left. If you do not specify values for the optional parameters,
a default length and a default minimum number of significant
digits is used.
If the size of 'x' is greater than 32, the defaults are 20
characters for the length and 19 characters for the minimum
number of digits. Otherwise, the defaults are 11 characters for
the length and 10 characters for the minimum number of digits.
Because the default length is 1 greater than the number of
significant digits, positive numbers will be preceded by a blank
and negative numbers will be preceded by a minus sign.
3 – EQ
The EQ function returns a Boolean value that specifies if the
parameters are equal according to the ASCII values of the
strings' characters.
Syntax:
EQ( str1,str2 )
The parameters 'str1' and 'str2' must be character-string
expressions. If the EQ function detects unequal string lengths,
it stops comparison and returns FALSE.
4 – FIND_MEMBER
The FIND_MEMBER function locates the first character in a string
that is a member of a specified set and returns an integer value
indicating the position of the character in the string; the
function returns 0 if the characters in the string were not
members of the set.
Syntax:
FIND_MEMBER( string, char-set )
The 'string' parameter is a string value, and the 'char-set' is
a value of type SET OF CHAR.
5 – FIND_NONMEMBER
The FIND_NONMEMBER function locates the first character in a
string that is not a member of a specified set and returns an
integer value indicating the position of the character in the
string; the function returns 0 if the characters in the string
were all members of the set.
Syntax:
FIND_NONMEMBER( string, char-set )
The 'string' parameter is a string value, and the 'char-set' is
a value of type SET OF CHAR.
6 – GE
The GE function returns a Boolean value that specifies if the
first parameter is greater than or equal to the second
parameter, according to the ASCII values of the strings'
characters.
Syntax:
GE( str1,str2 )
The parameters 'str1' and 'str2' must be character-string
expressions. VSI Pascal does not pad shorter strings with
blanks.
7 – GT
The GT function returns a BOOLEAN value that specifies if the
first parameter is greater than the second parameter, according
to the ASCII values of the strings' characters.
Syntax:
GT( str1,str2 )
The parameters 'str1' and 'str2' must be character-string
expressions. VSI Pascal does not pad shorter strings with
blanks.
8 – HEX
The HEX function returns a character-string value that is the
hexadecimal equivalent of the specified parameter. The return
value is compatible with all other string types.
Syntax:
HEX( x [[, length[[, digits]]]] )
The parameter 'x' is the expression to be converted. This
parameter must have a size that is known at compile time; it
cannot be VARYING OF CHAR, a conformant parameter, or a schema
type.
Two optional integer parameters specify the length of the
resulting string and the minimum number of significant digits to
be returned. If you specify a length that is too short to hold
the converted value, the resulting string is truncated on the
left. If you do not specify values for the optional parameters,
a default length and a default number of significant digits is
used.
By default, the number of significant digits is the minimum
number of characters necessary to express all the bits of the
converted parameter. This default length is one character more
than the default number of digits, which causes a leading blank
to be included in the resulting string when both parameters are
omitted.
9 – INDEX
The INDEX function searches a string for a specified substring
and returns an integer value that either indicates the location
of the substring or the status of the search.
Syntax:
INDEX( string, substring )
INDEX requires two character-string expressions as parameters:
a string to be searched and a substring to be found.
The search ends as soon as the first occurrence of the substring
is located. If the substring is found, INDEX returns the string
component that contains the first letter of the substring. If
the substring is not found, INDEX returns the value 0. If the
substring is an empty string, INDEX returns the value 1. If the
string to be searched is an empty string, INDEX returns the
value 0 unless the substring is also empty; in which case, INDEX
returns the value 1.
10 – LE
The LE function returns a Boolean value that specifies if the
first parameter is less than or equal to the second parameter,
according to the ASCII values of the strings' characters.
Syntax:
LE( str1,str2 )
The parameters 'str1' and 'str2' must be character-string
expressions. VSI Pascal does not pad shorter strings with
blanks.
11 – LENGTH
The LENGTH function returns an integer value that is the length
of a specified string expression.
Syntax:
LENGTH( str )
The parameter 'str' must be a character-string expression.
12 – LT
This function returns a Boolean value that specifies if the
first parameter is less than the second parameter, according to
the ASCII values of the strings' characters.
Syntax:
LT( str1,str2 )
The parameters 'str1' and 'str2' must be character-string
expressions. VSI Pascal does not pad shorter strings with
blanks.
13 – NE
The NE function returns a Boolean value that specifies if the
parameters are not equal according to the ASCII values of the
strings' characters.
Syntax:
NE( str1,str2 )
The parameters 'str1' and 'str2' must be character-string
expressions. VSI Pascal does not pad shorter strings with
blanks.
14 – OCT
The OCT function returns character-string value that is the
octal equivalent of the specified parameter. The return value
is compatible with all other string types.
Syntax:
OCT( x [[, length[[, digits]]]] )
The parameter 'x' is the expression to be converted. This
parameter must have a size that is known at compile time; it
cannot be VARYING OF CHAR, a conformant parameter, or a schema
type.
Two optional integer parameters specify the length of the
resulting string and the minimum number of significant digits to
be returned. If you specify a length that is too short to hold
the converted value, the resulting string is truncated on the
left.
By default, the number of significant digits is the minimum
number of characters necessary to express all the bits of the
converted parameter. This default length is one character more
than the default number of digits, which causes a leading blank
to be included in the resulting string when both parameters are
omitted.
15 – PAD
The PAD function returns a character-string value, of the
specified size, that contains padded fill characters. The
return value is compatible with all other string types.
Syntax:
PAD( str,fill,size )
The parameter 'str' is a character-string value to be padded;
the parameter fill is a value of type CHAR to be used as the
fill character; and, the parameter 'size' is an integer value
indicating the size of the final string.
This string is composed of the original string followed by the
fill character, which is repeated as many times as is necessary
to extend the string to its specified size. The final size must
be greater than or equal to the length of the string to be
padded.
16 – READV
The READV procedure reads characters from a character-string
expression and assigns them to parameters in the READV call.
The behavior of READV is analogous to that of READLN; the
character string is analogous to a one-line file.
Syntax:
READV( str, {variable-id[[ : radix-specifier ]]},...
[[, ERROR := error-recovery ]])
The parameter 'str' is the string to be read. The
variable-identifier is the variable to be assigned a value from
'str'. The parameter 'radix-specifier' can be BIN, OCT, or HEX.
You can read a variable of any type by using a radix specifier
except a type that contains a file component. The
'error-recovery' indicates the action to be taken in case of an
error.
An error occurs at run time if values have not been assigned to
all the parameters listed in the READV procedure call before the
end of the character string is reached.
17 – STATUSV
The STATUSV function returns an integer value that specifies the status of the last READV or WRITEV completed. It does not have any parameters. Note that if you have an asynchronous trap (AST) routine condition handler written in your program that uses READV and WRITEV, the call of STATUSV in your main program may not return the results you expected if an AST occurred between the READV/WRITEV and STATUS.
18 – SUBSTR
The SUBSTR function returns a substring (from a string specified
as a parameter) that is of the specified starting point and
length. The return value is compatible with all other string
types.
Syntax:
SUBSTR( str,start [,length] )
The parameter 'str' is a character string value; the parameter
'start' is an integer value that indicates the starting position
of the substring. The parameter 'length' is an integer value
that indicates the length of the substring. If the 'length'
argument is omitted, the length is computed to be the remainder
of the string value beginning at the starting position. The
'length' argument cannot be omitted on OpenVMS VAX systems. For
example,
SUBSTR(string,start_index)
is identical to
SUBSTR(string,start_index,length(string)-string_index+1)
When you use the SUBSTR function, the value of the starting
position must be greater than 0, the value of the length must be
greater than or equal to 0, and there must be enough characters
following the starting position to construct a substring of the
specified length.
19 – UDEC
The UDEC function returns a character-string value that is the
unsigned decimal equivalent of the specified parameter. The
return value is compatible with all other string types.
Syntax:
UDEC(x [[,length[[,digits]]]])
The parameter 'x' is the expression to be converted. The UDEC
function can take a parameter of any type except VARYING OF
CHAR, conformant parameters, or schema types. This function
requires the size of 'x' to be less than or equal to the size of
INTEGER64 (if supported) on your system. If your system does
not support INTEGER64, then the UDEC function requires that 'x'
be less than or equal to the size of INTEGER32.
Two optional integer parameters specify the length of the
resulting string and the minimum number of significant digits to
be returned. If you specify a length that is too short to hold
the converted value, the resulting string is truncated on the
left.
If you do not specify values for the optional parameters, a
default length and a default minimum number of significant
digits is used. If the size of 'x' is greater than 32, the
defaults are 21 characters for the length and 20 characters for
the minimum number of digits. Otherwise, the defaults are 11
characters for the length and 10 characters for the minimum
number of digits.
20 – WRITEV
The WRITEV procedure writes characters to a character-string
variable of type VARYING OF CHAR or discriminated STRING, by
converting the values of the parameters in the procedure call to
textual representations. The behavior of WRITEV is analogous to
that of the WRITELN function; the character-string parameter is
analogous to a one-line file.
Syntax:
WRITEV( str, parameter-list
[[,ERROR := error-recovery]] )
The parameter 'str' cannot appear within the parameter-list; if
you attempt to do this, unexpected results may occur. An error
occurs if WRITEV reaches the maximum length of the character
string before the values of all the parameters in the procedure
call have been written into the string. The parameter
'error-recovery' indicates the action to be taken if an error
occurs while the WRITEV procedure is executing.