Maintaining Distribution Lists Using the DSTBULK Subroutine

In this section:

How to:

The DSTBULK subroutine maintains Distribution Lists stored in BOTADDR and BOTDEST. It is a procedure-based call. With this subroutine, you can perform the following functions, using an external Distribution List residing on EDAPATH, or an HTML input form:

Note: These functions cannot be performed as a preprocessing procedure of the schedule being submitted.
Top of page
x
Syntax: How to Maintain Distribution Lists Using DSTBULK
-SET &var_name=DSTBULK(srv_userid,srv_userid_length,
-  'srv_userpass',srv_userpass_length,
-  'host_port',host_port_length,
-  'name',name_length,
-  'function',function_length,
-  'access',access_length,
-  'method',method_length,
-  'user',user_length,
-  'filename',filename_length,
-  'copy',copy_length,
-  'httpuser/pswd',httpuser/pswd_length, 
[- 'tcpiplevel',]
-  'I4');

where:

&var_name

Is the variable that will contain the return code.
Top of page
x
DSTBULK Subroutine Arguments

In this section:

 

The following sections describe the arguments for the DSTBULK subroutine. For an example that uses the DSTBULK subroutine, see Replacing Members in a Distribution List Using DSTBULK.

x
srv_userid Argument

Description

Valid Execution ID. It must match the user ID stored in the WebFOCUS repository.

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. It must match the password of the user ID stored in the WebFOCUS repository.

Required?

Yes

Format

A48

Valid Values

Alphanumeric characters and spaces are allowed.
x
srv_userpass_length Argument

Description

Length of the srv_userpass value.

Required?

Yes

Format

I4

Valid Values

Integer
x
hostname_port Argument

Description

Is the host name (or IP address) and port number of the web server on which the WebFOCUS Client is installed.

  • 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. For example, 
    'hostname:81',

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

C = Create a new Distribution List.

N = Add new members to an existing Distribution List.

R = Replace all members in an existing Distribution List.

D = Delete an existing Distribution List.
x
function_length Argument

Description

Length of the value of the function.

Required?

Yes

Format

I4

Valid Values

1
x
access Argument

Description

Length of the value of the function.

Required?

Yes, if function is C. Ignored if function is N, R, or D.

Format

A2

Valid Values

PR = Private Distribution List (other users cannot access the list).

PU = Public Distribution List (anyone can access the list).
x
access_length Argument

Description

Length of the value of the access allowed.

Required?

Yes, if access is supplied.

Format

I4

Valid Values

2
x
method Argument

Description

Distribution method for a new Distribution List.

Required?

Yes, if function is C. Ignored if function is N, R, or D.

Format

A5

Valid Values

FTP or F = FTP distribution.MAIL or M = email distribution. PRINT or P = Printer distribution.

x
method_length Argument

Description

Length of the value for the distribution method.

Required?

Yes, if function is C.

Format

I4

Valid Values

Integer
x
user Argument

Description

One of the following:

  • User ID of the owner of the target Distribution List when copy is not present. The target Distribution List is the one being created, added to, replaced, or deleted.
  • User ID of the owner of the source Distribution List when copy is present. The owner of the target Distribution List is the Execution ID, passed as the first argument to the subroutine.

Required?

Yes

This feature enables a logon user to create or manipulate a Distribution List for another user, whose ID is supplied on owner.

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
user_length Argument

Description

Length of the user argument.

Required?

Yes

Format

I4

Valid Values

Integer
x
filename Argument

Description

Name of the external source file used to supply member names. The following requirements apply:

  • The file must be located in EDAPATH (Windows and UNIX), or in a partitioned data set (PDS) allocated to ddname EDARPC (OS/390).
  • The file must have the extension .fex on Windows and UNIX, although you do not specify it.

Note: This is similar to the way the IBIB_filename parameter is used for DSTDLBULK. For more information, see Creating an External File.

Required?

Yes, if supplying members from an external file when function is C, N, or R.

Format

A8

Valid Values

First character must be alphanumeric. Single quotation marks and ampersands are not allowed. Blank lines are not allowed in an external distribution file.
x
filename_length Argument

Description

Length of the name of the external source file.

Required?

Yes, if filename is supplied.

Format

I4

Valid Values

I4
x
copy Argument

Description

Name of the source Distribution List. Applies when function is one of the following:

  • C, which copies an existing Distribution List to a new Distribution List.
  • N, which appends an existing Distribution List to another one.
  • R, which replaces an existing Distribution List with another one.

Required?

Yes, if supplying members from a Distribution List.

Format

A50

Valid Values

First character must be alphabetic.
x
copy_length Argument

Description

Length of the name of the source Distribution List.

Required?

Yes, if copy is supplied.

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 DSTBULK returns to the calling procedure, indicating successful completion (0) or an error condition. For more information, see ReportCaster API Subroutine Messages.

Required?

Yes

Format

I4

Valid Values

'I4'
Example: Replacing Members in a Distribution List Using DSTBULK

The following Dialogue Manager procedure calls DSTBULK to replace members in an existing Distribution List with members from an external file. The procedure resides on a WebFOCUS Reporting Server for 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 = DSTBULK(
    -  'userid',6, 
3.  -  'mypass',6, 
4.  -  'ibihost',7, 
5.  -  'Managers',8, 
6.  -  'R',1, 
7.  -  'PU',2, 
8.  -  ' ',0, 
9.  -  'JXDMKT',6, 
10. -  'extfile1',8, 
11. -  ' ',0, 
12. -  ' ',0, 
13. -  'I4'); 
14. -IF &SUBERR EQ 0 GOTO EXIT;
    -INCLUDE DSTBLKER
    -WRITE SUBLOG &SUBERR
    -EXIT

The procedure runs as follows:

  1. The FILEDEF command establishes the location of a file named sublog.ftm. DSTBULK writes error codes and messages (if there are any) to this file, as coded in line 14. 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 DSTBULK. 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 'ibihost' and the port number is 80. The value 80 is not specified because it is the default. The length of the server name is 7.
  5. The name of the Distribution List that will be modified is 'Managers'. The length of the name is 8.
  6. The members in the Distribution List 'Managers' will be replaced with other members, as specified by the value 'R'. In this case, the source of the members is an external file. The length of the value 'R' is 1.
  7. When a new Distribution List is being created, the access allowed (public or private) must be specified. However, in this example, member names from an external file will replace member names in an existing Distribution List. Therefore, this value will be ignored even though it is coded. The length of the value 'PU' is 2.
  8. This line illustrates the required code for the arguments method and method_length. The argument method is an optional alphanumeric argument. It is only required if you are creating a new Distribution List. If you do not supply a value for an optional alphanumeric argument, you must code the line as shown to hold the position for the argument and to indicate a length of zero.
  9. The ID of the owner of the Distribution List is 'JXDMKT'. The length of that value is 6.
  10. The name of the external file that is the source of member names is 'extfile1'. The length of the name is 8. An external file is typically created by third-party software.
  11. This line illustrates the required code for the arguments copy and copy_length. The argument copy is an optional alphanumeric argument. It is only required if you are supplying member names from an existing Distribution List. If you do not supply a value for an optional alphanumeric argument, you must code the line as shown to hold the position for the argument and to indicate a length of zero.
  12. 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 our 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.
  13. The format of the value of the return code ('I4') is the last argument passed to the subroutine.
  14. 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 DSTBLKER. DSTBLKER 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 DSTBLKER, see ReportCaster API Subroutine Messages.

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

WebFOCUS