SOUL $functions

From m204wiki
Jump to navigation Jump to search

Some operations are inefficient or impossible to code in a high-level programming language like SOUL. To overcome this difficulty, SOUL provides a variety of $functions. Many of these functions are deprecated in favor of an OO API method. When that is the case, the $function page notes the matching method.

The mathematical $functions, and those $functions central to a Model 204 product (and which require authorization of that product) are listed separately; you can find links to those sets of $functions in the following table:

$Function setDescription
$xxxmathMathematical $functions
$Fact_xxxSirFact $functions
$Ftp_xxxJanus FTP Server $functions
$Sock_xxxJanus Sockets $functions
$Web_xxxJanus Web Server $functions
Sir2000Sir2000 User Language Tools $functions

List of standard $functions

The following table lists available SOUL $functions, in alphabetical order. The list is not exhaustive (see the table of other $function sets, above).

Note: Some of the $functions listed below are only available with the purchase of a Model 204 add-on product. The individual page containing such a $function's full description has an itemized list of the add-on products that authorize the use of the $function.

See also:

  • Using functions, which reviews coding in SOUL with $functions
  • Notation conventions, which provides a description of the conventions used in syntax on individual $function pages.
$FunctionDescription
$AbbrevDetermine if string is abbreviation within list of words
$AccountAccount under which the user is logged in.
$AcctUser ID under which the user is logged in.
$AlphaWhether a string is composed of only the letters A through Z.
$AlphNumWhether a string is composed of only the letters A through Z and digits 0 through 9.
$Arr_FindFind value within array
$Arr_InitInitialize every element of array to specific value
$Arr_MaxFind maximum value in array
$Arr_MinFind minimum value in array
$ArrSizeNumber of elements in a particular dimension of an array.
$AsciiInput string, converted from EBCDIC to ASCII.
$A2ETranslate ASCII to EBCDIC
$Base64_DecodeConvert from base 64 to byte string
$Base64_EncodeConvert byte string to base 64
$BgPurgeCancel "long" sdaemon request initiated with $CommBg
$BgQueryList of "long" sdaemon requests initiated via $CommBg
$BinaryA number converted into fixed-point binary.
$Bind_ListReturn list of bound semaphores onto a $list
$BindFast, easy synchronization of system wide resource
$BitAndBitwise AND of two integers
$BitOrBitwise OR of two integers
$BldProcEnables a request to build a temporary procedure.
$Buffer_PositionCurrent Universal Buffer position.
$Buffer_SizeSize of user's Universal Buffer.
$Buffer_UsedAmount of data currently in Universal Buffer
$BumpBump a user
$CenqCtNumber of unused entries within the resource enqueuing table.
$CenterCenter string
$CfStatLList of statistics for users holding critical file resources
$ChkModWhether the terminal operator entered data in any full-screen input field.
$ChkPatSyntax of a pattern.
$ChkpInfInformation about checkpoints
$ChkTagWhether any erroneous full-screen input has been entered by the end user.
$CloseClose file or group in User Language request
$CmsDetermine if online is running under CMS
$CodeEncoding facility.
$CommandExecute Model 204 command on sdaemon, results to image
$CommBgExecute Model 204 commands on sdaemon
$CommndLExecute Model 204 command on sdaemon, results to $list
$ContextDetermine if string is name of open file or group
$CurfileName of the file from which the current record has been selected.
$CurrecInteger equal to the internal number of the current record.
$C2DConvert binary byte string to integer
$C2XA translation of each byte within a character string to its two-byte hexadecimal representation.
$DaemonMasterNumberGet user number of master thread
$DaemonParentNumberGet user number of parent thread
$Date
Current date in yy-mm-dd format.
$DateChgSpecified number of days, added to or subtracted from a given date.
$DateChkWhether a given date is valid.
$DateCnvDate converted to a format specified by the user.
$DateDifDifference in days between two dates.
$DateJCurrent date in "yy.ddd" format.
$DatePCurrent date in "dd mon yy" format.
$DAYDay name of the input day-number.
$DayINumber reflecting current day of the week.
$DeblankSubstring of a string, with leading and trailing blanks removed.
$DecodeDecoding facility.
$DeflateCompress a longstring with Deflate
$DelChRemove characters from string, compress and strip blanks
$Delg_SubsysDelete subsystem-wide global
$Delg_SysDelete system-wide global
$DelimrInsert delimiter string into input string at regular positions
$DscrDecoding facility.
$DsnData set name when you specify a file's DD name and the ordinal number.
$DsnNumTotal number of data sets defined for a file when you specify the file's DD name.
$D2CBinary byte representation of integer
$D2XHex representation of integer
$EbcdicConvert input string from ASCII to EBCDIC
$EcbDGetGet string data associated with an Event Control Block (ECB)
$EcbDSetSet string data associated with an Event Control Block (ECB)
$EcbTestCheck an Event Control Block (ECB) to see if it is posted
$EcfStatReturns the detailed completion code from the previous EXTERNAL statement.
$EditEdited numeric and alphanumeric text
$EdScanScan list of entities in online
$EformatExponent notations from converted numeric values
$EncryptA one-way encryption of a character string.
$Ent_PrintSet automatic character entity substitution
$Ent_Tabretrieve/modify character entity substitution table
$EntDo character entity substitution
$EnterEfficient terminal dialogue with users of data entry applications.
$ErrClrClears the error message text returned by the $ErrMsg and $Fsterr functions.
$ErrMsgPrefix and text of the last counting error or request cancellation message received.
$ErrSetIncrement or clear number of counting errors, set $ErrMsg
$E2ATranslate EBCDIC to ASCII
$FakeEntPrepare fake ENTER to automatically satisfy next full screen read
$FDefString that describes the attributes of a field in a Model 204 file.
$Field_ImageReturn field values into an image
$Field_ListReturn field values into a $list
$Field_ListIReturn field values into a $list mapped to an image
$FieldgroupIdThe ID of the current field group. (Available as of Model 204 version 7.5.)
$FieldgroupOccurrenceThe current occurrence number of the field group. (Available as of Model 204 version 7.5.)
$FIniTimFile initialization YYDDDMMHHSSTH
$FiStatRetrieve file's statistics into string
$FiStatLRetrieve set of files' statistics into list
$FldLenLength of a field.
$FloatFloating-point to a 4-byte string without conversion (4-byte floating point number to a 4-byte string).
$FloatDFloating-point to a 4-byte string without conversion (8-byte floating point number to an 8-byte string).
$FlsAccUser's access rights to a particular field.
$FlsChkWhether a given set of field level security accesses is valid for a field.
$FreeOptFree optional file or group from subsystem
$FsterrVariable-length string containing the prefix and the first counting error message or request cancellation message received by the user since the last time the count was reset to zero.
$FunForcCancel running or waiting Fast/Unload request
$FunImgRetrieve data from active Fast/Unload request into image
$FunList$list of active and enqueued Fast/Unload requests
$FunLoadFast/Unload records in Model 204 list or found set
$FunPurgPurge running or waiting Fast/Unload request
$FunSkipSkip to next output record for $FunImg, $FunsStr
$FunsStrRetrieve data from active Fast/Unload request into string
$FunWaitWait until asynchronous Fast/Unload request completes
$GetgInformation stored by a $SETG function.
$GetLLine number of the current line on the page on the user's terminal or on the output data set specified by a USE command.
$GetPPage number currently on the user's terminal or on the output data set specified by a USE command.
$GrmLocLocation of a missing member.
$GrmNameFile name of a missing member.
$GrnLeftNumber of optional files that may fail before MAXFAIL is exceeded.
$GrnMissNumber of missing members.
$GunZipDecompress a longstring with GUNZIP
$GZipCompress a longstring with GZip
$HexAConvert hexadecimal string to EBCDIC equivalent
$HPageString of special characters whose length is equal to the value specified as the $HPage argument.
$HshA hash value from a converted string value. A hash value is a distinct numeric representation of a given string value.
$IHexAConvert EBCDIC string to hexadecimal equivalent
$ImgInfRetrieve image item by variable name
$ImgOvlReplace image item value
$IncrgPerforms simple arithmetic on global variables.
$IncStatIncrement local system statistic
$IndexAfter comparing two strings, a number equal to the first position within the first string at which the second string appears; the same function as $SCAN.
$InflateDecompress a longstring with inflate
$ItsOpenWhether or not a file is open.
$ItsRemoteWhether the current file or group is remote or scattered.
$JobAuthDetermine if user has authorization for USE $JOB
$JobcodeAllows a request that is part of one step of a Model 204 batch run to communicate with a subsequent step.
$JpStatRetrieve Janus port's statistics into string
$JpStatLRetrieve statistics for set of Janus pors into $list
$LangSpcString containing the binary value of a character in a specified language.
$LangSrtA binary string translated to sort according to the NLSORT macro for the specified language.
$LangUstPreviously $LangSrt'ed string translated back to its original form.
$LenLength of a value in a field.
$List_Add_OrderedAdd an item to an ordered $list
$List_Add_Unique_OrderedConditionally add an item to an ordered $list
$List_Add_UniqueConditionally add an item to a $list
$List_CaptureCapture print data to $list
$List_Conv_ItemConvert $list to single delimited $list item
$List_Copy_ItemsCopy items between $lists
$List_Diff_ItemDifferences between $list and delimited $list item
$List_Global and $List_SessionAccess/create global/session $list
$List_Global_Del and $List_Session_DelDelete global/session $lists
$List_Global_List and $List_Session_ListList global/session $lists
$List_MaxILReturn maximum $list item length
$List_PrintDisplay contents of a $list
$ListAdd_LstrAdd longstring as new $list item
$ListAddAdd string as new $list item
$ListAddIAdd image as new $list item
$ListAdjAdjust length of $list item
$ListChkValidate a $list identifier
$ListCmpCompare two $lists and produce $list describing differences
$ListCntNumber of items in $list
$ListCpyCopy $list
$ListDelRelease CCATEMP storage used for $list
$ListFindFind string in $list
$ListFindI and $ListFindI_UpFind image item in $list
$ListFindI_SubBuild $list subset based on image item
$ListILnLength of $list item
$Listimg_CopyCopy a $list's image association
$ListImgAssociate an image with a $list
$ListInf_LstrRetrieve $list item into longstring
$ListInfRetrieve $list item into string
$ListInfIRetrieve $list item into image
$ListIns_LstrInsert string into a $list
$ListInsInsert string into a $list
$ListInsIInsert image into a $list
$ListLocLocate string in $list
$ListLupLocate string in $list, searching backwards
$ListMoveMove a $list
$ListNewCreate empty $list
$ListNewACreate array of empty $lists
$ListNewAICreate array of empty $lists associated with image
$ListNewICreate empty $list associated with image
$ListOvlOverlay part of $list item with string
$ListOvlIOverlay part of $list item with image item
$ListRemRemove item from $list
$ListRep_LstrReplace a $list item with a longstring
$ListRepReplace a $list item with a string
$ListRepIReplace $list item with an image
$ListRstRestore global $list
$ListSav and $ListSaveSave global $list
$ListSavLCount and names of available global $lists
$ListSort and $ListSrtSort $list
$ListSubCreate $list that is subset of input $list
$ListUpdProduce $list from input $list using $list of updates
$LowcaseA lower case string translated from an uppercase or mixed case string
$LstFldField names in a file, along with their field descriptions, into an image.
$LstProcInformation that is stored for a procedure.
$Lstr_Add_UserBufferAdd longstring to user buffer
$Lstr_Base64_DecodeConvert from base 64 to byte string
$Lstr_Base64_EncodeConvert byte string to base 64
$Lstr_C2XConvert byte string to hexadecimal
$Lstr_Get_Image and $Lstr_Set_ImageLongstring to/from image
$Lstr_Get_UserbufferGet user buffer contents to a longstring
$Lstr_Global and $Lstr_SessionBind to global/session longstring
$Lstr_Global_Del and $Lstr_Session_DelDelete global or session longstring
$Lstr_Global_Get and $Lstr_Session_GetGet global or session longstring
$Lstr_Global_Set and $Lstr_Session_SetSet global or session longstring
$Lstr_IndexFind a string inside a longstring
$Lstr_LeftLeftmost characters of a longstring
$Lstr_LenLength of a longstring
$Lstr_ParsePart of longstring preceding character in delimiter set
$Lstr_ParseXPart of longstring following character in delimiter set
$Lstr_RightRightmost characters of a longstring
$Lstr_Set_UserBufferSet user buffer to longstring value
$Lstr_SubstrSubstring of a longstring
$Lstr_SubWordSubstring of a longstring using word counts
$Lstr_TranslateTranslate longstring
$Lstr_UnblankRemove extraneous blanks from longstring
$Lstr_WindexReturn the position of a word within a long string
$Lstr_WordReturn a word from a long string
$Lstr_WordsReturn the number of words in a long string
$Lstr_X2CConvert from hexadecimal to byte string
$LstrTreat a string as longstring
$MisGrupGroup name if the error occurred in group context, null if in file context.
$MisLocLocation of a missing member or file.
$MisNameFile name of a missing member or file.
$MisNumNumber of files that failed in a group.
$MisStmtStatement that caused the ON unit to be entered.
$ModRemainder that results when one argument is divided by the another argument.
$OccursWhether a field has the OCCURS attribute.
$OneofTable lookup that can replace a series of IF conditions.
$PackPacked decimal representation of a string.
$PadDesignated character padded to the left.
$PadRDesignated character padded to the right
$ParsePart of string preceding character in delimiter set
$ParseXPart of string following character in delimiter set
$PostIndicates that an event has occurred; the thread waiting on an ECB can resume processing.
$PrcLEx$list of information about procedures in file
$PrcLExG$list of information about procedures in group or file
$PriortyChange a user's priority
$Proc_List$list of information about procedures in file
$Proc_ListG$list of information about procedures in group or file
$Proc_TouchChange a procedure's last-update date and user
$ProcClsClose procedure before reaching end
$ProcDatAdd lines from procedure to $list
$ProcGetNext line of procedure
$ProcLocLocate any of set of strings in procedure
$ProcOpnOpen procedure for $ProcDat, $ProcGet, $ProcLoc
$Random_SeedBuild seed specifying series of $Random results
$RandomGet next random number
$RdProcLines of a User Language procedure, retrieved in sequential order, that is stored in a Model 204 file.
$ReadAn echo of the data a user enters as a request is evaluated
$ReadInvPerforms the same function as $READ, except that input from the terminal is not echoed.
$ReadLcAn echo of the data a user enters as a request is evaluated, except that case translation is deactivated, regardless of the current *UPPER or *LOWER setting.
$RegexMatchWhether string matches regex
$RegexReplaceReplace matching strings
$RemoteVTAMNAME value of the originating Model 204 region when using SNA Communications Server (formerly VTAM) TRANSFER to transfer between Model 204 regions.
$ResetNReset or view M204 parameter
$ReverseReversed order of a string.
$RlcFileName of the file in which the last record locking conflict occurred.
$RlcRecInternal record number for which the last record locking conflict occurred.
$RlcUidID of the user who caused an ON FIND CONFICT or ON RECORD LOCKING CONFLICT. If the conflicting user is on a remote node, $RLCUID also returns the name of the node.
$RlcUsrUser number of the user with which the request conflicted when the last record locking conflict occurred.
$RoundNumber, rounded to a specified number of decimal places.
$ScanAfter comparing two strings, a number equal to the first position within the first string at which the second string appears; the same function as $INDEX.
$SclassCurrent user's subsystem user class.
$Screen_attrGet screen item attributes as a blank-delimited string
$Screen_clearClear tagged and/or modified attributes in a screen
$Screen_modSet modified attribute for a screen item
$ScrHideHide lines in SCREEN
$ScrSizeChange size of field on SCREEN
$ScrWideAllow SCREEN to accept fields wider than 79
$Session, $Session_Id, $Session_Owner,   
and $Session_Timeout
Return values for currently open session
$Session_CloseClose an open session
$Session_CreateCreate a new session
$Session_DeleteDelete a session
$Session_ListGet list of sessions
$Session_OpenOpen a session
$Setg_Subsys_ListGet list of subsystem-wide globals
$Setg_SubsysSet subsystem-wide global
$Setg_Sys_ListGet list of system-wide globals
$Setg_SysSet system-wide global
$SetgA created or changed entry in the global variable section of GTBL.
$SetLSets the current line counter for the output device currently in effect.
$SetPSets the current page number for the output device currently in effect.
$SetStatSet local system statistic
$Sir_Date
Get current datetime
$Sir_DateFmtValidate datetime format
$Sir_DateN
Current date and time as number of seconds/300
$Sir_DateNDCurrent date as number of days
$Sir_DateNMCurrent date and time as number of milliseconds
$Sir_DateNSCurrent date and time as number of seconds
$Sir_Date2NConvert datetime string to number of seconds/300
$Sir_Date2NDConvert datetime string to number of days
$Sir_Date2NMConvert datetime string to number of milliseconds
$Sir_Date2NSConvert datetime string to number of seconds
$Sir_LoginPerform secured web or sockets login
$Sir_ND2DateConvert datetime number of days to string
$Sir_NM2DateConvert datetime number of milliseconds to string
$Sir_NS2DateConvert datetime number of seconds to string
$Sir_N2DateConvert datetime number of seconds/300 to string
$Sir_WildTest string against a wildcard string
$SirJGetPlace audit trail data on $list
$SirMsgLine of current $SirMsgP procedure
$SirMsgPLoad procedure for retrieval via $SirMsg
$SirParmSet user-specific value, controlling Sirius products
$SirProdDetermine availability of Sirius product or capability
$SirSiteCurrent Sirius customer site ID
$SirTimeCurrent time as YYDDDHHMISSXX
$SirVerCurrent version number of Sirius product
$SirWarnSend warning or message to user(s)
$SlstatsResets the recording of since-last statistics anywhere within a request.
$SndMailSend an email message
$SndxSOUNDEX code of an argument.
$SquareA number multiplied by itself.
$SsStatRetrieve subsystem's statistics into string
$SsStatLRetrieve statistics for set of subsystems into $list
$StatCurrent value of any user statistic.
$StatDCalculate differences and rates for statistics strings
$StatLDCalculate differences and rates for statistics $lists
$StatusThe success or failure of the last executed external I/O or program communication statement.
$StatusDMore detailed description of a condition returned by $STATUS.
$StrTreat a longstring as string
$StrAndBit-wise AND two strings
$StripA number with suppressed leading zeros.
$StrOrBit-wise OR two strings
$StrXorBit-wise exclusive OR two strings
$SubCntCount occurrences of one string in another
$SubErsRemove occurrence of one string from another
$SubInsInsert string inside another string
$SubRepReplace occurrences of string
$SubstrSubstring of a string.
$SubsysStatus of an APSY subsystem.
$SyStatRetrieve system statistics into string
$TableCInformation provided by TABLEC command
$TermIdTerminal ID of current user thread
$TimeCurrent time in hh:mm:ss format.
$TkStatRetrieve task's statistics into string
$TkStatLRetrieve statistics for all tasks into $list
$TsoAttAttach program in user's TSO address space
$TsoCallCall program in user's TSO address space
$TsoCanCancel program invoked via $TsoAtt
$TsoCmdInvoke command in user's TSO address space
$TsoExecInvoke CLIST in user's TSO address space
$TsoExitTerminate TSO full screen interface session, stack command
$TSOIdTSO userid user's thread
$TSOStatStatus of program invoked via $TsoAtt
$TSOWaitWait for program invoked via $TsoAtt to complete
$UnbinValue converted from binary to string representation.
$Unbind_and_$UnbindW$Unbind and $UnbindW: Unbind resource previously bound via $Bind
$UnblankContents of an argument, removing leading and trailing blanks, and compressing multiple embedded blanks to one blank character.
$UnfloatCharacter string that represents a numeric counted string of 4 or 8 bytes, which contains a floating point.
$UnpackUnpacked decimal data
$UnPostResets a specified Event Control Block (ECB) to an unposted state.
$UnqRec

In the case of a uniqueness violation, returns the file-relative record number of the record that already contains the field name = value pair

If no uniqueness violation occurred. returns -1.

$UnSpaceNormalize spaces and quotes
$UpcaseAn uppercase string converted from a lower or mixed case string.
$UpdateName of the group update file or the current file.
$UpdFileName of the file in which a field level constraint violation has occurred, or a blank if no violation occurred.
$UpdFldName of the field for which a field level constraint violation has occurred, or a blank if no violation occurred.
$UpdLocLocation name (node name) of the current update unit (Parallel Query Option/204 only).
$UpdOvalValue of the original field occurrence causing a constraint violation, when invoked from an ON FCC unit following the detection of an AT-MOST-ONE field-level constraint conflict.
$UpdRecFile-relative record number of the record whose update caused a field level constraint violation, or -1 if no violation occurred.
$UpdStatNumeric value denoting the type of field level constraint violation that has occurred, or 0 if no violation occurred.
$UpdStmtType of User Language updating statement causing a field level constraint violation, or a blank if no violation occurred.
$UpdValField value causing a field level constraint violation, or a blank if no violation occurred.
$UseASAPrevent carriage control in USE output
$UserUser's user number.
$UseridUser ID under which the user is logged in.
$UsrPrivWhether a user ID has been granted specific Model 204 privileges.
$UsStatRetrieve user's statistics into string
$UsStatLRetrieve statistics for set of users into $list
$VerifyWhether every character in one string is present in a second string.
$ViewValue of a parameter.
$VnumWhether a given argument is in a valid format for a SORT BY VALUE NUMERICAL statement or for any type of mathematical operation.
$WaitSuspend a user until an Event Control Block (ECB) is posted.
$WakeUpPause user until specified time
$Web_xxxList of Janus Web Server $functions
$WindexWord number of first occurrence of word in phrase
$WordP word in a specified string, delimited by a blank or optionally specified character.
$WordsNumber of words in a specified string, delimited by a blank or optionally specified character.
$X2COne-byte EBCDIC characters translated from a string of 2-byte hexadecimal character.
$X2DConvert hex string to integer

Using functions

You can use functions in several ways, including, as a term in:

  • An expression in a variable assignment statement, for example:

%X=$EDIT(2573,'99999')

  • The specifications in a PRINT statement

A PRINT statement can include a function call anywhere a field name can be used. For example:

PRINT $EDIT(2573,'99999')

  • An expression in a conditional statement, for example:

IF $EDIT(2573,'99999') EQ 02573 THEN...

  • An expression which serves as the argument to another function, for example:

%L=$LEN($EDIT(2573,'99999'))

The direct use of function calls in some statements, such as FIND, results in compilation errors.

Comparing successful and unsuccessful $function code

If your request is coded as follows:

BEGIN $EDIT(2573,'99999') END

The following error is your result:

*** 1 M204.0229: INVALID STATEMENT $EDIT(2573,'99999')

However, if you code your request as follows, it works properly:

BEGIN PRINT $EDIT(2573,'99999') * Or * * %X=$EDIT(2573,'99999') * END

Function return values

Each function returns a single value to the calling request. For example, this function sets %A equal to the user's login account name:

%a = $account

This function causes the length of the current value of the FULLNAME field to be compared to 10:

IF $LEN(FULLNAME) GT 10 THEN . . .

Function arguments

Some functions require one or more arguments which allow you to pass information to the subroutine. Some functions take no arguments. Arguments must be enclosed in parentheses and separated by commas. For example:

IF $READ('CONTINUE?') EQ 'YES' THEN . . . %X = $mod(COUNT IN CT, %BASE)

Rules for function arguments

Function arguments follow the normal rules for arithmetic expressions. Arguments can include other function calls and can perform any type of computation. See the section Expressions for detailed information on expression syntax.

Argument evaluation and conversion

Model 204 evaluates each argument to a function as either a string or a number. When this data type conflicts with the data type required by the function, the following rules apply:

  • If an argument is expected to be numeric but is a string, Model 204 converts the string to a number according to the conversion rules described in the assignment statement discussion in Relationship between %variable assignment and declaration and Conversion.
  • If an argument is expected to be a string but is numeric, Model 204 converts the number to a string.
  • If the original number contains decimal places, they are lost during the conversion.

User-written functions

In addition to the functions provided by SOUL, some customer sites write their own functions based on their particular needs. Before using any user-written functions, make sure that your site's FUNU module has been reassembled with the macro library supplied with the current release. Also, please be sure to carefully test your user-written functions before your system goes into production.

Notes:

  • It is recommended that all user-written functions use the STMG/LMG Assembly Language instructions to save and restore any registers that are modified.
  • The RESULT macro does not work in Model 204 Version 5.1 and later. Change any use of the RESULT macro in $functions to use the standard LEAVENUM, LEAVEF0 and LEAVESTR macros.
  • In addition to the above considerations, see the installation instructions relating to FUNU.

Customers are individually responsible for any functions they write. Rocket Software takes no responsibility for user-written functions or their documentation.