Opening lists by using code

Typically, lists are opened by the user choosing an item in the Navigation Pane on the left side of the Microsoft Dynamics GP main window. You can also open lists by using sanScript code.

When a user opens a list through the Navigation Pane, the list content is displayed in the main window. When a list is opened through code, it can be displayed in the main window or in a separate window for the list. Restrictions can also be passed to the list to restrict the information being displayed.

Opening a list

Microsoft Dynamics GP can display one card list, one trasaction list, and one report list at a time. The lists can be in either the main Microsoft Dynamics GP window or in a separate window. To open a list, use the List_Open procedure of the syListObj form.

The List_Open procedure must always be called with the background keyword to prevent conflicts with other list code that may be running.

Before you open a list using sanScript code, you must verify that a list of that type is not already open. If a list of the specified type is already open, your code should display a message indicating this to the user.

The following example shows how to verify whether a card list is already open. If one is not, a specific card list can be opened.

local boolean list_is_open;
local string list_name;

{Assume that a list of the specified type is not open.}
list_is_open = false;

if isopen(form syCardList) then
	if (ListObjState:IsCreated of window CardList of form syCardList) then

		{A list is already open. Tell the user which list to close.}
		call GetListPropertiesForListID of form syListObj,
			GetListDictID(ListObjState of window CardList of form syCardList) of form syListObj,
			GetListID(ListObjState of window CardList of form syCardList) of form syListObj, none, list_name;

		{Set the flag indicating the list is open.}
		list_is_open = true;

		{Display a message indicating the situation for the user.}
		warning "You need to close the list: " + list_name;
	end if;
end if; 

if list_is_open = false then
	{Call to open list using the List_Open procedure}
end if;

The following example shows how to verify whether a transaction list is already open. If one is not, a specific transaction list can be opened.

local boolean list_is_open;
local string list_name;

{Assume that a list of the specified type is not open.}
list_is_open = false;

if isopen(form syTrxList) then
	if (ListObjState:IsCreated of window TrxList of form syTrxList) then

		{A list is already open. Tell the user which list to close.}
		call GetListPropertiesForListID of form syListObj, 
			GetListDictID(ListObjState of window TrxList of form syTrxList) of form syListObj,
			GetListID(ListObjState of window TrxList of form syTrxList) of form syListObj, none, list_name;

		{Set the flag indicating the list is open.}
		list_is_open = true;

		{Display a message indicating the situation for the user.}
		warning "You need to close the list: " + list_name;
	end if;
end if; 

if list_is_open = false then
	{Call to open list using the List_Open procedure}
end if;

The following example shows how to verify whether a report list is already open. If one is not, a specific report list can be opened.

local boolean list_is_open;
local string list_name;

{Assume that a list of the specified type is not open.}
list_is_open = false;

if isopen(form syReportList) then
	if (ListObjState:IsCreated of window ReportList of form syReportList) then

		{A list is already open. Tell the user which list to close.}
		call GetListPropertiesForListID of form syListObj,
			GetListDictID(ListObjState of window ReportList of form syReportList) of form syListObj,
			GetListID(ListObjState of window ReportList of form syReportList) of form syListObj, none, list_name;

		{Set the flag indicating the list is open.}
		list_is_open = true;

		{Display a message indicating the situation for the user.}
		warning "You need to close the list: " + list_name;
	end if;
end if; 

if list_is_open = false then
	{Call to open list using the List_Open procedure}
end if;

Retrieving restriction parameters

If you use the optional restriction parameters for the List_Open procedure, you will need to retrieve them to use when processing the content for the list being opened. Typically, they are retrieved and used in the Refresh procedure for the list.

The restriction parameters for the List_Open procedure are optional. They can be used in addition to the standard restrictions defined for lists.

If you supply the restriction parameters for the List_Open procedure, their values will be temporarily stored as properties for the command that is used to add the list to the Microsoft Dynamics GP navigation. For instance, the command named ListObj_Leads is defined to open the Leads sample card list. If the List_Open procedure is used to open the Leads card list, and the optional restriction parameters are supplied, they will be temporarily stored with the List_Obj_Leads command.

You can retrieve the property values from the list command by using the Command_GetNamedProperty() function. The following table lists the constants defined in the syListObj form that correspond to the named properties that will be set for the command used to open the list.

Constant	Description
NAMEDPROP_RESTRICTIONTYPE	The optional integer restriction parameter.
NAMEDPROP_RESTRICTIONSTRING1	The first string restriction parameter.
NAMEDPROP_RESTRICTIONSTRING2	The second string restriction parameter.

The following example shows how these named properties are retrieved for the Leads card list in the sample integrating application.

local string restriction_integer;
local string restriction_string1;
local string restriction_string2;

restriction_integer = Command_GetNamedProperty(tag, NAMEDPROP_RESTRICTIONTYPE of form syListObj);
restriction_string1 = Command_GetNamedProperty(tag, NAMEDPROP_RESTRICTIONSTRING1 of form syListObj);
restriction_string2 = Command_GetNamedProperty(tag, NAMEDPROP_RESTRICTIONSTRING2 of form syListObj);