Maintaining Single Distribution List Members Using the DSTMEM Subroutine

In this section:

How to:

The DSTMEM subroutine maintains single members in a Distribution List stored in BOTDEST. It is a procedure-based call. With this subroutine, you can:


Top of page

x
Syntax: How to Maintain Single Distribution List Members Using DSTMEM
-SET &var_name=DSTMEM(srv_userid,srv_userid_length,
-  'srv_userpass',srv_userpass_length,
-  'host_port',host_port_length,
-  'name',name_length,
-  'function',function_length,
-  'owner',user_length,
-  'fldvlu',fldvlu_length,
-  'destfn',destfn_length,
-  'httpuser/pswd',httpuser/pswd_length, 
[- 'tcpiplevel',]
-  'I4');

where:

&var_name

Is the variable that will contain the return code.


Top of page

x
DSTMEM Subroutine Arguments

In this section:

 

The following sections describe the arguments for the DSTMEM subroutine. For an example that uses the DSTMEM subroutine, see Adding a New Member to a Distribution List Using DSTMEM.



x
srv_userid Argument

Description

Valid Execution ID.

Required?

Yes

Format

A48 (Windows and UNIX)A8 (OS/390)

Valid Values

Single quotation marks, ampersands, and spaces are not allowed. First character must be alphanumeric (OS/390).



x
srv_userid_length Argument

Description

Length of the user ID.

Required?

Yes

Format

I4

Valid Values

Integer



x
srv_userpass Argument

Description

Valid password for the Execution ID.

Required?

Yes

Format

A48

Valid Values

Alphanumeric characters and spaces are allowed.



x
srv_userpass_length Argument

Description

Length of the password for the Execution ID.

Required?

Yes

Format

I4

Valid Values

Integer



x
hostname_port Argument

Description

Is the connection information to the web or application server where the WebFOCUS web application is deployed. The connection information includes the host name, port number, web context root information for the WebFOCUS web application, and the ReportCaster web context root. For example:

'hostname:port/webfocus_context_root:rcaster_context_root'
  • hostname (or IP address) and port number of the web server on which the WebFOCUS Client is installed. This must be separated by a colon. The maximum character length is 30.

    If the port number is 80 (the default), you may omit the colon and port number. For example, hostname.

    If the port number is not 80, use a colon as a delimiter and then specify the port number. The maximum port number character length is 10. For example, hostname:81.

  • webfocus_context_root is the WebFOCUS web application context root. The default is ibi_apps. The maximum character length for the context root is 40.
  • rcaster_context_root is required to be the same value as the webfocus_context_root. The maximum character length for the context root is 40.

    Note: Hard coded references to the ReportCaster rcaster context root or a ReportCaster specific context root in ReportCaster Subroutine API calls or Web application URLs are not supported in Release 8. For more information, contact Customer Support.

Required?

Yes

Format

A64

Valid Values

No restrictions.



x
hostname_port_length Argument

Description

Is the length of the host name and port number. This is only the length of the host name if the port number is omitted.

Required?

Yes

Format

I4

Valid Values

Integer



x
name Argument

Description

Name of the Distribution List that will be modified.

Required?

Yes

Format

A50

Valid Values

First character must be alphabetic.



x
name_length Argument

Description

Length of the name of the Distribution List.

Required?

Yes

Format

I4

Valid Values

Integer



x
function Argument

Description

Type of maintenance action that will be performed.

Required?

Yes

Format

A1

Valid Values

A = Add a new member. D = Delete an existing member.



x
function_length Argument

Description

Length of the value of the function.

Required?

Yes

Format

I4

Valid Values

1



x
owner Argument

Description

User ID of the Distribution List owner being added to or deleted from.

Required?

Yes

Format

A48 (Windows and UNIX)A8 (OS/390)

Valid Values

Single quotation marks, ampersands, and spaces are not allowed. First character must be alphanumeric.



x
user_length Argument

Description

Length of the user ID of the owner of the Distribution List being added to or deleted from.

Required?

Yes

Format

I4

Valid Values

Integer



x
fldvlu Argument

Description

Field value on which the report is burst.

Required?

Yes, if the report is burst.

Format

A75

Valid Values

Burst value



x
fldvlu_length Argument

Description

Length of the burst value.

Required?

Yes, if fldvlu is supplied.

Format

I4

Valid Values

I4



x
destfn Argument

Description

Destination of the report or report section.

Required?

Yes

Format

A75

Valid Values

File name if the method is FTP. Email address if the method is MAIL. Printer name if the method is PRINT.



x
destfn_length Argument

Description

Length of the destination value.

Required?

Yes

Format

I4

Valid Values

Integer



x
httpuser/pswd Argument

Description

Web server user ID and password.

Required?

Yes, if the web server is running with security on.

Format

A75

Valid Values

Valid web server user ID and password.



x
httpuser/pswd_length Argument

Description

Length of the web server user ID and password, including the forward slash character ( / ).

Required?

Yes, if httpuser/pswd is supplied.

Format

I4

Valid Values

Integer



x
tcpiplevel Argument

Description

Method ReportCaster uses for securing sockets from TCP/IP, based on a specific SAS/C library.

Required?

Yes, if the WebFOCUS Reporting Server runs on OS/390.

Format

I4

Valid Values

1 = Resolves special connectivity problems. 0 = Specifies no special connectivity problems.



x
returncode Argument

Description

Value that DSTMEM returns to the calling procedure, indicating successful completion (0) or an error condition.

Required?

Yes

Format

I4

Valid Values

'I4'



Example: Adding a New Member to a Distribution List Using DSTMEM

The following Dialogue Manager procedure calls DSTMEM to add a new member to a Distribution List. The procedure resides on a WebFOCUS Reporting Server on Windows. The numbers to the left of the code refer to the annotations that follow.

1. FILEDEF SUBLOG DISK D:\ibi\srv77\wfs\catalog\sublog.ftm
    -RUN 
2.  -SET &SUBERR = DSTMEM(
    -  'userid',6, 
3.  -  'mypass',6, 
4.  -  'ibiwnt:3794',11, 
5.  -  'Managers',8, 
6.  -  'A',1, 
7.  -  'listownerId',11, 
8.  -  &VAR1,&VAR2, 
9.  -  &VAR3,&VAR4, 
10. -  ' ',0, 
11. -  'I4'); 
12. -IF &SUBERR EQ 0 GOTO EXIT;
    -INCLUDE DSTMEMER
    -WRITE SUBLOG &SUBERR
    -EXIT

The procedure runs as follows:

  1. The FILEDEF command establishes the location of a file named sublog.ftm. DSTMEM writes error codes and messages (if there are any) to this file, as coded in line 12. The -RUN command executes the FILEDEF command.

    For more information about the FILEDEF command, see the Developing Reporting Applications manual.

  2. The -SET Dialogue Manager command calls the ReportCaster API subroutine DSTMEM. It sets the amper variable &SUBERR to the value of the return code that is provided on successful, or non-successful, completion of the subroutine.

    The Execution ID ('userid'), included in single quotation marks, and length of 'userid' (6), are the first arguments passed to the subroutine.

  3. The Execution ID password ('mypass') and length of the password (6) are passed to the subroutine.
  4. The name of the WebFOCUS Reporting Server is ibiwnt and the port number is 3794. The length of this string is 11. The string is enclosed in single quotation marks.
  5. The name of the Distribution List that will be modified is 'Managers'. The length of the name is 8.
  6. A new member name will be added to the Distribution List, as specified by the value 'A'. The length of the value 'A' is 1.
  7. The ID of the owner of the Distribution List is 'listownerId'. It is 11 characters in length.
  8. This line illustrates the required code for the arguments fldvlu and fldvlu_length. The argument fldvlu is an optional alphanumeric argument. It is only required if the report is burst.
  9. In this example, these amper variables are where you can enter the email address (&VAR3) and the length of the email address (&VAR4) to be added to the Distribution List. There are no single quotation marks around the amper variables.
  10. This line contains the code for the arguments httpuser/pswd and httpuser/pswd_length. These arguments are required only if the web server is running with security on. In this example, web server security is off, so values for the arguments are not supplied. However, the line must be coded as shown to indicate the position of the argument and a length of zero.
  11. The format of the value of the return code ('I4') is the last argument passed to the subroutine.
  12. The error handling code tests the value of &SUBERR, which holds the return code from the subroutine. If the return code is 0, which indicates successful completion of the subroutine, the procedure terminates.

    If it is a non-zero value, indicating an error condition, the procedure continues to the next line, which incorporates the supplied file DSTMEMER. DSTMEMER translates return codes into meaningful messages. Messages are written to the file sublog.ftm, which was defined by the FILEDEF command in the first line of code.

    For more information about DSTMEMER, see ReportCaster API Subroutine Messages.

Note: The initial hyphen and space on each line are required for a continuation line.


WebFOCUS