SOUL $functions: Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
Line 238: Line 238:
<ul>
<ul>
<li>SMTPCADD is the default SMTP client address, the TCP/IP domain for the operating system, for the $SNDMAIL function. You can specify SMTPCADD as:</li>
<li>SMTPCADD is the default SMTP client address, the TCP/IP domain for the operating system, for the $SNDMAIL function. You can specify SMTPCADD as:</li>
</li>
<ul>
<li>(z/OS, z/VM, or z/VSE) Internet Protocol (IP) address, IPv4 format. </li>
<li>(z/OS) Domain name of up to 255 bytes. If the first character of the address is an alphabetic character (A to Z), it is automatically evaluated as a domain name.</li>
<li>(z/OS) IPV6 address, with up to 8 halfwords separated by colons, such as:
<code>C0:12:46:F0:00:00:00:01</code>, which can also be written as <code>C0:12:46:F0::01</code>. In other words, the double colon shows that there are missing halfwords of binary zeros.</li>
</ul>
</ul>
<p>(z/OS, z/VM, or z/VSE) Internet Protocol (IP) address, IPv4 format. </p>
You can override SMTPCADD for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function call.</li>
<p>(z/OS) Domain name of up to 255 bytes. If the first character of the address is an alphabetic character (A to Z), it is automatically evaluated as a domain name.</p>
<p>(z/OS) IPV6 address, with up to 8 halfwords separated by colons, such as:</p>
<p><var>C0:12:46:F0:00:00:00:01</var>, which can also be written as <var>C0:12:46:F0::01</var>. In other words, the double colon shows that there are missing halfwords of binary zeros.</p>
<p>You can override SMTPCADD for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function call.</p>
<ul>
<li>SMTPCPRT is the default SMTP client port for the $SNDMAIL function. The value can be any value in the user range--normally above 4095 and up to 32767.</li>
<li>SMTPCPRT is the default SMTP client port for the $SNDMAIL function. The value can be any value in the user range--normally above 4095 and up to 32767.</li>
<p>You can override SMTPCPRT for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function call.</p>
<p>You can override SMTPCPRT for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function call.</p>
</li>
</li>
<li>SMTPSADD is the default SMTP server address for the $SNDMAIL function. You can specify SMTPSADD as:</li>
<li>SMTPSADD is the default SMTP server address for the $SNDMAIL function. You can specify SMTPSADD as:
<ul>
<li>(z/OS, z/VM, or z/VSE) Internet Protocol (IP) address, IPv4 format.</li>
<li>(z/OS) Domain name of up to 255 bytes. If the first character of the address is an alphabetic character (A to Z), it is automatically evaluated as a domain name.</li>
<li><p>(z/OS) IPV6 address, with up to 8 halfwords separated by colons, such as:</p>
<code>C0:12:46:F0:00:00:00:01</code>, which can also be written as <code>C0:12:46:F0::01</code>. In other words, the double colon shows that there are missing halfwords of binary zeros.</li>
</ul>
<p>You can override SMTPSADD for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function call.</p>
</li>
</li>
</ul>
<p>(z/OS, z/VM, or z/VSE) Internet Protocol (IP) address, IPv4 format.</p>
<p>(z/OS) Domain name of up to 255 bytes. If the first character of the address is an alphabetic character (A to Z), it is automatically evaluated as a domain name.</p>
<p>(z/OS) IPV6 address, with up to 8 halfwords separated by colons, such as:</p>
<p><var>C0:12:46:F0:00:00:00:01</var>, which can also be written as <var>C0:12:46:F0::01</var>. In other words, the double colon shows that there are missing halfwords of binary zeros.</p>
<p>You can override SMTPCADD for a specific calls by entering a different value in the EMAILD argument of the $SNDMAIL function call.</p>
<ul>
<li>SMTPSPRT is the default SMTP server port for the $SNDMAIL function. SMTPSPRT is normally set to the standard SMTP value of 25. You can override SMTPSPRT for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function.</li>
<li>SMTPSPRT is the default SMTP server port for the $SNDMAIL function. SMTPSPRT is normally set to the standard SMTP value of 25. You can override SMTPSPRT for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function.</li>
</li>
</li>

Revision as of 21:33, 17 May 2013

Overview

Some operations are inefficient or impossible to code in a high-level programming language like User Language. To overcome this difficulty, User Language provides a variety of functions, which are assembly language subroutines you can call from within a User Language request.

The name of each User Language function begins with a dollar sign ($). For this reason, they are often referred to as $functions (dollar functions).

Types of functions

Functions provided by User Language

The functions provided by User Language are divided into two sets. One set is supplied as a standard feature and includes functions for data editing, data validation, and other purposes. The other set of functions (mathematical functions) is an optional feature of Model 204 and contains mathematical and scientific subroutines.

In order to save machine resources, your site might have chosen to omit some of the standard functions as well as some or all of the mathematical functions. If a request calls a function that is not yet installed, compile-time errors result.

User-written functions

In addition to the functions provided by User Language, 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.

Note

It is recommended that all user-written functions use the STMG/LMG Assembly Language instructions to save and restore any registers that are modified.

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

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.

Sending email messages via User Language

The User Language $SNDMAIL function simplifies sending an email message to issuing a single function call. You can easily send an email message using User Language without writing a procedure and without having an extensive knowledge of sockets or SMTP protocol.

Internet Protocol (IP) addressing

On z/OS systems only, M204 supports both IPv6 and IPv4 addressing.

Limitations of the $SNDMAIL function under z/VM and z/VSE

$SNDMAIL is supported with the following exceptions:

  • The SMTPCADD and SMTPSADD addresses must be supplied in internet protocol (IP) address protocol, not as domain names. You must supply IPv4 (dotted-decimal) internet addresses for the SMTPCADD and SMTPSADD parameters.
  • Likewise, if the client and server names are specified using the SMAILD image rather than using the CCAIN parameters SMTPCADD and SMTPSADD, the SERVERDDNAME and CLIENTDDNAME values must be supplied rather than the SERVERNAME and CLIENTNAME values.
  • Model 204 does not support IPv6 addressing on z/VM or z/VSE systems.

Enabling $SNDMAIL

The first requirement for enabling the use of $SNDMAIL is to set the following four required CCAIN parameters:

Parameter SMTP purpose
SMTPCADD SMTP client address. The client is the Model 204 address space.
 

On z/OS systems:

Set this parameter to one of the following:

Symbolic name, such as MYMVS1, or SMTP.MYDOMAIN.COM.

Dotted decimal address, such as 182.148.55.206.

IPV6 address, with up to 8 halfwords separated by colons, such as C0:12:46:F0:00:00:00:01, which can also be written as C0:12:46:F0::01. In other words, the double colon shows that there are missing halfwords of binary zeros.

 

On z/VM or z/VSE systems:

Set this parameter to the dotted decimal address, such as 182.148.55.206.

SMTPCPRT SMTP client port. The default value is 7700.
SMTPSADD SMTP server address.
 

On z/OS systems:

Set this parameter to one of the following:

Symbolic name, such as MYMVS1, or SMTP.MYDOMAIN.COM.

Dotted decimal address, such as 182.148.55.206.

IPV6 address, with up to 8 halfwords separated by colons, such as C0:12:46:F0:00:00:00:01, which can also be written as C0:12:46:F0::01.

 

On z/VM or z/VSE systems:

Set this parameter to the dotted decimal address, such as 182.148.55.206.

SMTPSPRT SMTP server port. The default value is 25, which is standard for most SMTP servers.

Your system manager can dynamically reset these parameters while the run is up. If you use the domain name for either SMTPCADD or SMTPSADD, you must have the following DD allocated to the Online:

//SYSTCPD DD DSN=TCPIP.PROFILE(TCPDATA),DISP=SHR

This is the TCP/IP profile data set required to support the resolution of IP domain names.

On some SMTP servers, a valid email address is required for the %FROM argument in the $SNDMAIL function. Most SMTP activity requires a valid SMTP server.

$SNDMAIL and BATCH204

$SNDMAIL is supported in BATCH204 if you relink BATCH204 with the following objects after V7R4 installation:

  • TC62 (or TC62DOS on z/VSE systems)
  • TCIU
  • TCSE
  • LU62
  • FUNR (or FUNRDOS on z/VSE systems)

After relinking you need to ensure that the following SMTP parameters are set in the ONLINE and BATCH204 CCAIN:

  • SMTPCADD
  • SMTPSADD
  • SMTPCPRT
  • SMTPSPRT

$SNDMAIL

The $SNDMAIL function sends an email message using the values you enter for the $SNDMAIL arguments. The $SNDMAIL function lets you send an email message with an optional binary attachment.

As of Version 7.5, an attachment can be translated to ASCII before sending it.

Syntax

The syntax for the $SNDMAIL function is:

$SNDMAIL(%SUBJ,%RCPT,%BODY,%FROM,%TO,%CC,%BCC,'EMAILD',%BINARY,'C')

Where:

  • %SUBJ, which is optional, specifies a %variable or literal that contains the topic line.
  • %RCPT, which is optional, specifies a %variable or an image that contains the destination addresses, separated by commas.
  • If %RCPT is omitted, the destination addresses are taken from the %TO, %CC and %BCC arguments.

    If %RCPT is an image, the image name must be enclosed within quotation marks, for example 'DEPT-ADDR'.

  • %BODY specifies a %variable or an image that contains the text of the message. If %BODY is an image, the image name must be enclosed in quotation marks, for example 'MSG-TXT'.
  • %FROM specifies a %variable that contains the FROM header field of up to 255 bytes. Although %FROM is optional, you should supply it, otherwise messages could fail when speaking to another SMTP server. If %FROM is omitted, the logged-on user ID is used. The email server may append the domain name to the given %FROM value.
  • %TO, %CC, and %BC, which are optional, specify a %variable that contains the TO, CC, and BCC header fields, respectively, of up to 255 bytes each.
  • Address must be enclosed in carets (<>), for example: M204-help <M204support@rocketsoftware.com>.

  • 'EMAILD', which is optional, specifies image data. If 'EMAILD' is present, it must be in the following format:
  • TITLE 'EMAILD - IMAGE WITH SMTP PARAMETERS' EMAILD DS 0F EMAILD MAPS IMAGE EMSERVPT DS F SERVER PORT EMCLNTPT DS F CLIENT PORT EMSERV DS CL255 SERVER NAME EMCLIENT DS CL255 CLIENT NAME EMSERVDD DS CL15 SERVER DOTTED DECIMAL ADDRESS EMCLNTDD DS CL15 CLIENT DOTTED DECIMAL ADDRESS EMSERVD6 DS CL45 SERVER IPV6 PRESENTATION FORMAT EMCLNTD6 DS CL45 CLIENT IPV6 PRESENTATION FORMAT EMAILDL EQU *-EMAILD LENGTH OF BLOCK PASSED IN IMAGE

    The EMSERVD6 and EMCLNTD6 fields are provided for the IPv6 colon-separated network addresses. These two fields are optional, to provide backward compatibility.

    If 'EMAILD' is omitted, the default values that are defined by CCAIN startup parameters--SMTPCADD, SMTPCPRT, SMTPSADD, and SMTPSPRT--are used.

  • %BINARY, which is optional, specifies a %variable or literal with the name of a binary attachment that will be appended to the message. The binary object is assumed to be in the Universal Buffer at offset 0 (also called position 1). The length of the attachment is defined by the $BUFFER_USED value. If the %BINARY parameter is omitted, there is no attachment.

    The function encodes the binary attachment using Base64 encoding.

  • 'C', which is optional and is available as of Version 7.5, specifies that the object in the buffer wil be translated to ASCII before being attached to the email. Alternatively, you can set this parameter to a percent variable with the value 'C'. Translation to ASCII is useful if the $SNDMAIL attachment is a CLOB (CHARACTER-LARGE-OBJECT) such as a text document.

    In this example:

    %RC = $SNDMAIL(%SUBJECT,,%BODY,%FROM,%TO,,,,'CLOB.TXT','C')

    the CLOB.TXT attachment will be translated to ASCII before being attached to the email.

Setting CCAIN parameters for $SNDMAIL

You can set the following CCAIN parameters as default values for $SNDMAIL.

  • SMTPCADD is the default SMTP client address, the TCP/IP domain for the operating system, for the $SNDMAIL function. You can specify SMTPCADD as:
    • (z/OS, z/VM, or z/VSE) Internet Protocol (IP) address, IPv4 format.
    • (z/OS) Domain name of up to 255 bytes. If the first character of the address is an alphabetic character (A to Z), it is automatically evaluated as a domain name.
    • (z/OS) IPV6 address, with up to 8 halfwords separated by colons, such as: C0:12:46:F0:00:00:00:01, which can also be written as C0:12:46:F0::01. In other words, the double colon shows that there are missing halfwords of binary zeros.
    You can override SMTPCADD for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function call.
  • SMTPCPRT is the default SMTP client port for the $SNDMAIL function. The value can be any value in the user range--normally above 4095 and up to 32767.
  • You can override SMTPCPRT for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function call.

  • SMTPSADD is the default SMTP server address for the $SNDMAIL function. You can specify SMTPSADD as:
    • (z/OS, z/VM, or z/VSE) Internet Protocol (IP) address, IPv4 format.
    • (z/OS) Domain name of up to 255 bytes. If the first character of the address is an alphabetic character (A to Z), it is automatically evaluated as a domain name.
    • (z/OS) IPV6 address, with up to 8 halfwords separated by colons, such as:

      C0:12:46:F0:00:00:00:01, which can also be written as C0:12:46:F0::01. In other words, the double colon shows that there are missing halfwords of binary zeros.

    You can override SMTPSADD for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function call.

  • SMTPSPRT is the default SMTP server port for the $SNDMAIL function. SMTPSPRT is normally set to the standard SMTP value of 25. You can override SMTPSPRT for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function.

Examples of running $SNDMAIL

Example 1

%FROM = 'me@mydomain.com' %TO = 'My Friend <you@yourdomain.com>' %BNAME = 'mypicture.jpg' MODIFY BUFFER CLEAR IN LOBSVR FOR 1 RECORD WHERE SVRKEY = %SVRKEY %ISIZE = $LOBLEN(SVRLOB) PRINT 'SIZE OF ' WITH %SVRKEY WITH ' IS ' WITH %ISIZE BUFFER, 1, %ISIZE = SVRLOB, 1, %ISIZE END FOR PRINT 'BUFFER USED IS ' WITH $BUFFER_USED %SUBJECT = 'THIS SENDS A JPG FROM LOBSVR - ' WITH %SVRKEY %BODY = 'THIS BODY CONTAINS ' WITH %SVRKEY %RC = $SNDMAIL(%SUBJECT,,%BODY,%FROM,%TO,,,,%BNAME)

In the previous example, a binary object (BLOB) is retrieved from the database and placed at position 1 in the buffer. The $SNDMAIL function sends this as a Base64-encoded attachment.

Note: The second parameter (the RCPTTO addresses) is omitted. The function creates this using the %TO parameter.

Example 2

%TO ='JANE <YOU@YOURCORP.COM>' %BODY='See you at 9:30 AM tomorrow in the conference room' %RC =$SNDMAIL(,,%BODY,,%TO)

Example 3

The EMAILD argument is used to override the default domain names and ports.

IMAGE EMAILD SERVERPORT IS BINARY LEN 4 CLIENTPORT IS BINARY LEN 4 SERVERNAME IS STRING LEN 255 CLIENTNAME IS STRING LEN 255 SERVERDD IS STRING LEN 15 HOSTDD IS STRING LEN 15 END IMAGE PREPARE IMAGE EMAILD %EMAILD:SERVERNAME = 'MAIL.SERVER.COM' %EMAILD:CLIENTNAME = 'MYMVSSYSTEM' %EMAILD:SERVERPORT = 25 %EMAILD:CLIENTPORT = 5601 %FROM = 'ME@MYCORP.COM' %TO = 'JANE <YOU@YOURCORP.COM>' * RCPTTO is defined as an image here, allowing the string of * addressees to be more than 255 bytes long. IMAGE RCPTTO EMRCPT1 IS STRING LEN 255 END IMAGE PREPARE IMAGE RCPTTO %RCPTTO:EMRCPT1 = 'YOU@YOURCORP.COM' IMAGE BODY BODY1 IS STRING LEN 240 BODY2 IS STRING LEN 240 END IMAGE PREPARE IMAGE BODY %S = 'EXAMPLE 1' /? SUBJECT LINE  ?/ %BODY:BODY1 = 'THIS IS BODY1 WHICH IS PART OF AN IMAGE' %BODY:BODY2 = 'SO THE BODY TEXT CAN BE MORE THAN 255 BYTES LONG' %RC = $SNDMAIL(%S,'RCPTTO','BODY',%FROM,%TO,,,'EMAILD')

Example 4

This example illustrates using EMAILD in an IPV6 environment. The lines that differ from Example 3 are shown in bold.

IMAGE EMAILD SERVERPORT IS BINARY LEN 4 CLIENTPORT IS BINARY LEN 4 SERVERNAME IS STRING LEN 255 CLIENTNAME IS STRING LEN 255 SERVERDD IS STRING LEN 15 HOSTDD IS STRING LEN 15 SERVERD6 IS STRING LEN 45 CLIENTD6 IS STRING LEN 45 END IMAGE PREPARE IMAGE EMAILD %EMAILD:SERVERNAME = 'MAIL.SERVER.COM' %EMAILD:CLIENTD6 = 'C0:12:46:F0::01' %EMAILD:SERVERPORT = 25 %EMAILD:CLIENTPORT = 5601 %FROM = 'ME@MYCORP.COM' %TO = 'JANE <YOU@YOURCORP.COM>' * RCPTTO is defined as an image here, allowing the string of * addressees to be more than 255 bytes long. IMAGE RCPTTO EMRCPT1 IS STRING LEN 255 END IMAGE PREPARE IMAGE RCPTTO %RCPTTO:EMRCPT1 = 'YOU@YOURCORP.COM' IMAGE BODY BODY1 IS STRING LEN 240 BODY2 IS STRING LEN 240 END IMAGE PREPARE IMAGE BODY %S = 'EXAMPLE 1' /? SUBJECT LINE ?/ %BODY:BODY1 = 'THIS IS BODY1 WHICH IS PART OF AN IMAGE' %BODY:BODY2 = 'SO THE BODY TEXT CAN BE MORE THAN 255 BYTES LONG' %RC = $SNDMAIL(%S,'RCPTTO','BODY',%FROM,%TO,,,'EMAILD')

ASCII translation

All text, except an optional binary attachment, is translated from EBCDIC to ASCII before sending.

Line ends

Text that is part of the header and body can include EBCDIC CRLF strings (X'0D25') that are translated to ASCII along with the rest of the text.

Reserved names

The $SNDMAIL function uses Interface names CCAEM000 through CCAEM999. The user does not specify these names--the link name is generated by the function.

Socket limits

Up to 31 sockets are available on each link. If no more sockets are available on a particular link (CCAEM000, for example), the next link is tried. Thus, a maximum of 31,000 simultaneous email threads is theoretically possible.

Size of email message

The FROM, TO, CC, BCC, RCPTTO addresses, and body length, excluding the optional binary attachment, must total less than 27454 bytes.

Return code

The $SNDMAIL function returns a fixed full word binary return code. See Handling error condition return codes for possible values.

RCPTTO parameter

If the $SNDMAIL EMAILD argument is omitted, the RCPTTO addresses are constructed from the addresses contained in the %TO, %CC, and %BCC arguments.

The sum of the lengths of the RCPTTO address string, (If supplied) and the body text cannot exceed 30,700.

Using quotation marks

You must enclose the names of images within quotation marks, for example: 'BODY'. However, do not enclose the percent variable values within quotation marks, for example: %SUBJECT, not '%SUBJECT'.

Server and client names in the EMAILD parameters

In the EMAILD image, on a z/OS system, you can specify either or both the server and client names as domain names, for example: SMTPSERVER.YOURDOMAIN.COM or as an Internet Protocol (IP) address. If you specify the domain name, a TCP/IP call looks up the IP address.

  • If one field is present, all fields must be present, even if the optional fields are left blank.
  • If a name or port field is absent, it is taken from the CCAIN parameters SMTPSADD, SMTPCADD, SMTPSPRT, and SMTPCPRT.

The two port parameters have defaults: the SMTPSPRT default is 25; the SMTPCPRT default is 7700.

The two address parameters, SMTPSADD and SMTPCADD, can be specified either as domain names of up to 255 bytes or as IP addresses. If the address begins with an alphabetic character (A to Z), it is automatically evaluated as a domain name.

The four CCAIN default parameters SMTPSADD, SMTPCADD, SMTPSPRT, and SMTPCPRT can be examined using VIEW and changed using RESET.

References

For more information about the standards used in this function, please refer to these Internet Request for Comments documents:

  • RFC822, Standard for the format of ARPA Internet Text Messages
  • RFC2821, Simple Mail Transfer Protocol
  • RFC3548, The Base16, Base32, and Base64 Data Encoding

Error codes for $SNDMAIL

The $SNDMAIL function issues a return code. An error in $SNDMAIL gives a return code of -1, and it is $STATUSD that contains the error code.

The negative error codes starting with -999 are listed in Handling error condition return codes.

It is also possible that $SNDMAIL will return a positive error code, which comes from TCP/IP and is documented in the IBM TCP/IP documentation, TCP/IP V3.2 for MVS: API Reference, Appendix D. For example, an error code of 60 means that the connection attempt timed out. $SOCKET calls give the same errors.

However, in the case of a non-zero (error) return code, the following message is issued to the user:

M204.2799: $SNDMAIL ERROR errortext

When an attempt is made to set or reset the SMTPCADD or SMTPSADD parameters and the address translation fails, Model 204 issues the following messages:

RESET SMTPCADD CCAGGGG *** M204.2834: ADDRESS LOOKUP FAILED FOR CCAGGGG *** 1 M204.1123: PARAMETER SMTPCADD NOT RESET

Handling error condition return codes

Handling error condition return codes lists the possible $SOCKET return codes.

$Socket return codes
SMTP Error text Numeric value Meaning
ERBADARG -999 BAD ARGUMENT
ERNOTOPN -998 NOT OPEN
ERNOSTOR -997 NO STORAGE
ERIMAGER -996 IMAGE FAILURE
ERBADLNK -995 BAD LINK
ERNOTREL -994 SOCD NOT RELEASED
ERPHYERR -993 LINK DEAD
ERNOLINK -992 LINK UNKNOWN
ERTRUNC -991 VARIABLE TRUNCATION (READ CALL)
ERNOSOCK -990 SOCKET NOT FOUND
ERTRUNC2 -989 TRUNCATION ERROR ON IMAGE
EROPSYS -988 FUNCTION UNSUPPORTED ON THIS OPSYS
  -987 Not used
ERNOSRCD -986 NO SRCD
ERFDSLIM -985 TOO MANY SOCKETS
ERBADUBN -984 UNIVERSAL BUFFER NOT THERE
ERBADUBL -983 UNIVERSAL BUFFER LENGTH ERROR
ERBADUBA -982 UNIVERSAL BUFFER ALLOCATION ERROR
EREMREAD -981 ERROR WITH EMAIL SERVER READ
EREMWRIT -980 ERROR WITH EMAIL SERVER WRITE
ERGHBERR -979 SKIP=0 ERROR ON GETHOST CALL
ERGHERR1 -978 T1 LT 0 ERROR ON GETHOST CALL
ERGHERR2 -977 NO ADDRESSES RETURNED

When an error message (with code 5xx) is returned from the SMTP server, the following error message is displayed:

M204.2796: 'SMTP %C'

where %C is the error message returned by SMTP.

For the other error codes above, the following error message is returned, in addition to $STATUSD being set.

M204.2799: '$SNDMAIL ERROR %C'

where %C is listed in the following table:

Error text message possibilities for M204.2799
%C in message 2799 $STATUSD code(s)
IN PARAMETER 999
- SOCKET NOT FOUND 990
- FUNCTION NOT SUPPORTED ON THIS SYSTEM 998
- NO SRCD 986
- TOO MANY SOCKETS 985
WITH UNIVERSAL BUFFER 984, 983, 982
Reading from SMTP server 981
Writing to SMTP server 980
Using GETHOSTBYNAME lookup 979, 978, 977
GETTING STORAGE 997
IN IMAGE PROCESSING 996
WITH TCP LINK 995, 998, 993, 992
- SOCD NOT RELEASED 994
READING DATA - TRUNCATION 991

Summary of standard functions

The following table lists the standard SOUL functions in alphabetical order.

See also:

Function Returns...
$ACCOUNT Account under which the user is logged in.
$ACCT User ID under which the user is logged in.
$ALPHA Whether a string is composed of only the letters A through Z.
$ALPHNUM Whether a string is composed of only the letters A through Z and digits 0 through 9.
$ARRSIZE Number of elements in a particular dimension of an array.
$ASCII Input string, converted from EBCDIC to ASCII.
$BINARY A number converted into fixed-point binary.
$BLDPROC Enables a request to build a temporary procedure.
$BUFFER_POSITION Current Universal Buffer position.
$BUFFER_SIZE Size of user's Universal Buffer.
$BUFFER_USED Amount of data currently in Universal Buffer
$CENQCT Number of unused entries within the resource enqueuing table.
$CHKMOD Whether the terminal operator entered data in any full-screen input field.
$CHKTAG Whether any erroneous full-screen input has been entered by the end user.
$CHKPAT Syntax of a pattern.
$CODE Encoding facility.
$CURFILE Name of the file from which the current record has been selected.
$CURREC Integer equal to the internal number of the current record.
$C2X A translation of each byte within a character string to its two-byte hexadecimal representation.
$DATE Current date in yy-mm-dd format.
$DATECHG Specified number of days, added to or subtracted from a given date.
$DATECHK Whether a given date is valid.
$DATECNV Date converted to a format specified by the user.
$DATEDIF Difference in days between two dates.
$DATEP Current date in "dd mon yy" format.
$DAYI Number reflecting current day of the week.
$DEBLANK Substring of a string, with leading and trailing blanks removed.
$DECODE Decoding facility.
$DSCR Decoding facility.
$DSN Data set name when you specify a file's DD name and the ordinal number.
$DSNNUM Total number of data sets defined for a file when you specify the file's DD name.
$ECFSTAT Returns the detailed completion code from the previous EXTERNAL statement.
$EDIT Edited numeric and alphanumeric text
$EFORMAT Exponent notations from converted numeric values
$ENCRYPT A one-way encryption of a character string.
$ENTER Efficient terminal dialogue with users of data entry applications.
$ERRMSG Prefix and text of the last counting error or request cancellation message received.
$FDEF String that describes the attributes of a field in a Model 204 file.
$FLDLEN Length of a field.
$FLOAT Floating-point to a 4-byte string without conversion (4-byte floating point number to a 4-byte string).
$FLOATD Floating-point to a 4-byte string without conversion (8-byte floating point number to an 8-byte string).
$FLSACC User's access rights to a particular field.
$FLSCHK Whether a given set of field level security accesses is valid for a field.
$FSTERR Variable-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.
$GETG Information stored by a $SETG function.
$GETL Line number of the current line on the page on the user's terminal or on the output data set specified by a USE command.
$GETP Page number currently on the user's terminal or on the output data set specified by a USE command.
$GRMLOC Location of a missing member.
$GRMNAME File name of a missing member.
$GRNLEFT Number of optional files that may fail before MAXFAIL is exceeded.
$GRNMISS Number of missing members.
$HPAGE String of special characters whose length is equal to the value specified as the $HPAGE argument.
$HSH A hash value from a converted string value. A hash value is a distinct numeric representation of a given string value.
$INCRG Performs simple arithmetic on global variables.
$INDEX After 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.
$ITSOPEN Whether or not a file is open.
$ITSREMOTE Whether the current file or group is remote or scattered.
$JOBCODE Allows a request that is part of one step of a Model 204 batch run to communicate with a subsequent step.
$LANGSPC String containing the binary value of a character in a specified language.
$LANGSRT A binary string translated to sort according to the NLSORT macro for the specified language.
$LANGUST Previously $LANGSRTed string translated back to its original form.
$LEN Length of a value in a field.
$LOWCASE A lower case string translated from an uppercase or mixed case string
$LSTFLD Field names in a file, along with their field descriptions, into an image.
$LSTPROC Information that is stored for a procedure.
$MISGRUP Group name if the error occurred in group context, null if in file context.
$MISNAME File name of a missing member or file.
$MISNUM Number of files that failed in a group.
$MISLOC Location of a missing member or file.
$MISSTMT Statement that caused the ON unit to be entered.
$MOD Remainder that results when one argument is divided by the another argument.
$OCCURS Whether a field has the OCCURS attribute.
$ONEOF Table lookup that can replace a series of IF conditions.
$PACK Packed decimal representation of a string.
$PAD Designated character padded to the left.
$PADR Designated character padded to the right
$RDPROC Lines of a User Language procedure, retrieved in sequential order, that is stored in a Model 204 file.
$READ An echo of the data a user enters as a request is evaluated
$READINV Performs the same function as $READ, except that input from the terminal is not echoed.
$READLC An 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.
$REMOTE VTAMNAME value of the originating Model 204 region when using SNA Communications Server (formerly VTAM) TRANSFER to transfer between Model 204 regions.
$REVERSE Reversed order of a string.
$RLCFILE Name of the file in which the last record locking conflict occurred.
$RLCREC Internal record number for which the last record locking conflict occurred.
$RLCUID ID 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.
$RLCUSR User number of the user with which the request conflicted when the last record locking conflict occurred.
$ROUND Number, rounded to a specified number of decimal places.
$SCAN After 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.
$SCLASS Current user's subsystem user class.
$SETG A created or changed entry in the global variable section of GTBL.
$SETL Sets the current line counter for the output device currently in effect.
$SETP Sets the current page number for the output device currently in effect.
$SLSTATS Resets the recording of since-last statistics anywhere within a request.
$SNDX SOUNDEX code of an argument.
$SQUARE A number multiplied by itself.
$STAT Current value of any user statistic.
$STATUS The success or failure of the last executed external I/O or program communication statement.
$STATUSD More detailed description of a condition returned by $STATUS.
$STRIP A number with suppressed leading zeros.
$SUBSTR Substring of a string.
$SUBSYS Status of an APSY subsystem.
$TIME Current time in hh:mm:ss format.
$UNBIN Value converted from binary to string representation.
$UNBLANK Contents of an argument, removing leading and trailing blanks, and compressing multiple embedded blanks to one blank character.
$UNFLOAT Character string that represents a numeric counted string of 4 or 8 bytes, which contains a floating point.
$UNPACK Unpacked decimal data
$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.

$UPCASE An uppercase string converted from a lower or mixed case string.
$UPDATE Name of the group update file or the current file.
$UPDFLD Name of the field for which a field level constraint violation has occurred, or a blank if no violation occurred.
$UPDFILE Name of the file in which a field level constraint violation has occurred, or a blank if no violation occurred.
$UPDLOC Location name (node name) of the current update unit (Parallel Query Option/204 only).
$UPDOVAL Value 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.
$UPDREC File-relative record number of the record whose update caused a field level constraint violation, or -1 if no violation occurred.
$UPDSTAT Numeric value denoting the type of field level constraint violation that has occurred, or 0 if no violation occurred.
$UPDSTMT Type of User Language updating statement causing a field level constraint violation, or a blank if no violation occurred.
$UPDVAL Field value causing a field level constraint violation, or a blank if no violation occurred.
$USER User's user number.
$USERID User ID under which the user is logged in.
$USRPRIV Whether a user ID has been granted specific Model 204 privileges.
$VERIFY Whether every character in one string is present in a second string.
$VIEW Value of a parameter.
$VNUM Whether a given argument is in a valid format for a SORT BY VALUE NUMERICAL statement or for any type of mathematical operation.
$WORD P word in a specified string, delimited by a blank or optionally specified character.
$WORDS Number of words in a specified string, delimited by a blank or optionally specified character.
$X2C One-byte EBCDIC characters translated from a string of 2-byte hexadecimal character.