GetDistributionList

Purpose

Use GetDistributionList to retrieve either:

• The distribution list IDs that belong to a single application profile and mailbox.
• Or, the names of all the recipients on a single distribution list. Recipients can be individual mailboxes or other distribution lists.
  
  

  

  
  

Description

Before using GetDistributionList, you must set the Caller - Profile ID (SV20) and Caller : Mailbox - ID (SV32) system variables to retrieve the caller’s private distribution lists and all public distribution lists. If you do not set SV32, GetDistributionList cannot retrieve the caller’s private lists. When GetDistributionList is used to retrieve the distribution lists for an application profile that is not owned by the caller, only the IDs of public lists are retrieved.

Parameters

The parameters for GetDistributionList identify whether the action retrieves all the lists that match defined parameters, steps through a list of lists, or steps through the recipients on a list. The parameters differ, depending on the action.

• When the action is defined as Get First, you can select to retrieve one of the following:

  Distribution List IDs

  Retrieves a list of distribution list IDs defined for the following parameters:

  • Profile ID. Identifies the owner of the mailbox that contains the lists.
  • Mailbox ID. Identifies the mailbox that contains the lists. Valid values are 1 through 10.

The system variables set are:

• Distribution List - ID (SV120)
• Distribution List : List type (SV181)
• Distribution List : Number of lists left (SV124)

  Message Recipients

  Retrieves the recipients on a distribution list defined for the following parameters:

• Profile ID. Identifies the owner of the mailbox that contains the list.
• Mailbox ID. Identifies the mailbox that contains the list.
• List ID. Identifies the distribution list. Valid values are 1 through 10.

Each recipient on the list is defined by a profile ID, a mailbox ID, and a list ID:

• For recipients that are distribution lists, the profile ID identifies the owner of the mailbox that contains the list, the mailbox ID identifies the mailbox that contains the list, and the list ID identifies the distribution list.
• For recipients that are individual mailboxes, the profile ID identifies the owner of the recipient’s mailbox, the mailbox ID identifies the mailbox, and the list ID has a value of 0.

The system variables set are:

• Distribution List : Recipient profile ID (SV122)
• Distribution List : Recipient mailbox ID (SV123)
• Distribution List : Destination list ID (SV121) (value is 0 if the recipient is a mailbox)
• Distribution List : Number of recipients left (SV125)

• When the action is defined as Get Next, there are no parameters. Get Next steps through either a list of lists, or a list of the recipients on a list, depending on the parameters specified for the Get First action that precedes it.

Possible results

GetDistributionList can have one of the following results:

Succeeded

The action was successful.

Invalid List ID

The value of the variable specified for the List ID parameter does not identify a distribution list.

Invalid Profile ID

The value of the variable specified for the Profile ID parameter does not identify an application profile.

Invalid Mailbox ID

The value of the variable specified for the Mailbox ID parameter does not identify a mailbox for the application profile.

Access Denied

The state table could not access the mailbox. For example, a caller may have requested access to a mailbox to which the caller does not have access privileges.

End of Distribution List

The action retrieved the last list or the last recipient.

Host Problem

There is a system problem.

ASCII syntax

When using an ASCII editor, code this action with these parameters in the following order:

1. "GET_NEXT"

Or:

1. "GET_FIRST"
2. "DIST_LIST_IDS"
3. Profile ID
4. Mailbox ID

Or:

1. "GET_FIRST"
2. "MESSAGE_RECIPIENTS"
3. Distribution list ID
4. Profile ID
5. Mailbox ID

For example:

label: "Check Edges"
	GetDistributionList("GET_NEXT")
	  edge EDGE_GDL_COMPLETED:		   completed
	  edge EDGE_GDL_INVALID_LIST_ID:	 invalid_list_id
	  edge EDGE_GDL_INVALID_USER_ID:	 invalid_user_id
	  edge EDGE_GDL_INVALID_BOX_ID: 	 invalid_box_id
	  edge EDGE_GDL_ACCESS_NOT_ALLOWED:  access_not_allowed
	  edge EDGE_GDL_END_OF_LIST:		 end_of_list
	  edge EDGE_GDL_HOST_PROBLEMS: 	  host_problems
	;
	GetDistributionList("GET_FIRST", "DIST_LIST_IDS", in1_n, in2_n);
	GetDistributionList("GET_FIRST", "MESSAGE_RECIPIENTS", loc2_n,
                     in1_n, in2_n);

The parameters and edges are described above under "Parameters" and "Possible results". For more information, see Testing a state table using the debugger.