REQUEST Options

n = REQUEST (question_name, name_or_index, variable1 [, variable2, ...]) n = REQUEST{2} (question_name, name_or_index, name, variable1 [, variable2, ...]) n = REQUEST{3} (question_name, name, name_or_index_array, variable1 [, variable2, ...]) n = REQUEST{4} (question_name, name_or_index, index, name, variable1 [, variable2, ...])

The first parameter represents the question string while the second (or more) represents the object of the question (if it exists). The other parameters are variable names in which the return values (the answers) are stored.
The function’s return value is the number of the answer (in the case of a badly formulated question or a nonexistent name, the value will be 0).

ARCHICAD identifies the order and number of the input parameters by either the version of the REQUEST command, or the exact name (as string constant) of the request option. This means that using the first or both of the following options is the safest:

  • name of the request is always a constant string
  • version is added to the command

Returns information in the given variable(s)

Request Parameter Script Compatibility

The use of most requests in parameter scripts (or master scripts run as parameter script) can result in unstable returned values, therefore should be avoided.

Compatibility up to ARCHICAD 19: The use of most requests in parameter scripts (or master scripts run as parameter script) could result in unreliable returned values.
Compatibility starting from ARCHICAD 20: the following applies in parameter script cases:

  • the request expression will always have 0 as success return value
  • the requested values will contain a type-matching default only (empty string or 0)

Using these restricted requests in the parameter script will also generate GDL warnings starting from ARCHICAD 19.

To check the parameter script compatibility, refer to the table below:

Legend:
GDL_CheckIcon works without restriction
GDL_WarningIcon works (with additional warning)
GDL_ErrorIcon does not work: expression returns 0, while containing dummy type-matching defaults in returned variables (empty string or 0) – with additional warning

Compatibility in Parameter Script ARCHICAD 18 ARCHICAD 19 ARCHICAD 20
A
ANCESTRY_INFO GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
ANGULAR_DIMENSION GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
ANGULAR_LENGTH_DIMENSION GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
AREA_DIMENSION GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
ASSOCEL_PROPERTIES GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
ASSOCLP_NAME GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
ASSOCLP_PARVALUE GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
ASSOCLP_PARVALUE_WITH_DESCRIPTION GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
AUTOTEXT_LIST GDL_ErrorIcon
B
BUILDING_MATERIAL_INFO GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
C
CALC_ANGLE_UNIT GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
CALC_AREA_UNIT GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
CALC_LENGTH_UNIT GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
CALC_VOLUME_UNIT GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
CLASS_OF_FILL GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
CLEAN_INTERSECTIONS GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
COMPONENT_PROJECTED_AREA GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
COMPONENT_VOLUME GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
CONFIGURATION_NUMBER GDL_ErrorIcon
CONSTR_FILLS_DISPLAY GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
CUSTOM_AUTO_LABEL GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
D
DATETIME GDL_CheckIcon GDL_WarningIcon GDL_WarningIcon
DOOR_SHOW_DIM GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
E
ELEVATION_DIMENSION GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
F
FLOOR_PLAN_OPTION GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
FONTNAMES_LIST GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
FULL_ID_OF_PARENT GDL_WarningIcon GDL_ErrorIcon
H
HEIGHT_OF_STYLE GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
HOME_STORY GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
HOME_STORY_OF_OPENING GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
HOMEDB_INFO GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
I
ID_OF_MAIN GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
LAYOUT_LENGTH_UNIT GDL_CheckIcon GDL_WarningIcon GDL_WarningIcon
LAYOUT_TEXT_SIZE_UNIT GDL_CheckIcon GDL_WarningIcon GDL_WarningIcon
LEVEL_DIMENSION GDL_CheckIcon GDL_WarningIcon GDL_WarningIcon
LINEAR_DIMENSION GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
M
MATCHING_PROPERTIES GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
MATERIAL_INFO GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
MODEL_LENGTH_UNIT GDL_CheckIcon GDL_WarningIcon GDL_WarningIcon
MODEL_TEXT_SIZE_UNIT GDL_CheckIcon GDL_WarningIcon GDL_WarningIcon
N
NAME_OF_FILL GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
NAME_OF_LINE_TYPE GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
NAME_OF_LISTED GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
NAME_OF_MACRO GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
NAME_OF_MAIN GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
NAME_OF_MATERIAL GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
NAME_OF_PLAN GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
NAME_OF_PROGRAM GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
NAME_OF_STYLE GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
P
PEN_OF_RGB GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
PROGRAM_INFO GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
PROPERTIES_OF_PARENT GDL_ErrorIcon
PROPERTY_NAME GDL_ErrorIcon
PROPERTY_VALUE_OF_PARENT GDL_ErrorIcon
R
RADIAL_DIMENSION GDL_CheckIcon GDL_WarningIcon GDL_WarningIcon
REFERENCE_LEVEL_DATA GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
RGB_OF_MATERIAL GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
RGB_OF_PEN GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
S
SILL_HEIGHT_DIMENSION GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
STORY GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
STORY_INFO GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
STYLE_INFO GDL_CheckIcon GDL_WarningIcon GDL_WarningIcon
SUM_WITH_ROUNDING GDL_CheckIcon
T
TEXTBLOCK_INFO GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
W
VIEW_ROTANGLE GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
WINDOW_DOOR_DIMENSION GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
WINDOW_DOOR_SHOW_DIM GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
WINDOW_DOOR_ZONE_RELEV GDL_CheckIcon GDL_WarningIcon GDL_WarningIcon
WINDOW_DOOR_ZONE_RELEV_OF_OWNER GDL_CheckIcon GDL_WarningIcon GDL_WarningIcon
WINDOW_SHOW_DIM GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
WORKING_ANGLE_UNIT GDL_CheckIcon GDL_WarningIcon GDL_WarningIcon
WORKING_LENGTH_UNIT GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
Z
ZONE_CATEGORY GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
ZONE_COLUS_AREA GDL_CheckIcon GDL_WarningIcon GDL_ErrorIcon
ZONE_RELATIONS GDL_CheckIcon GDL_CheckIcon GDL_CheckIcon
ZONE_RELATIONS_OF_OWNER GDL_CheckIcon GDL_WarningIcon GDL_WarningIcon

Details of Requests

n = REQUEST ("Name_of_program", "", program_name)

Returns in the given variable the name of the program, e.g., “”.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

Example 1:
Printing the name of the program

n = REQUEST ("Name_of_program", "", program_name)
PRINT program_name

 

n = REQUEST ("Name_of_macro", "", my_name)
n = REQUEST ("Name_of_main", "", main_name)


After executing these function calls, the my_name variable will contain the name of the macro,
while main_name will contain the name of the main macro (if it doesn’t exist, empty string).

n = REQUEST ("ID_of_main", "", id_string)


For library parts placed on the floor plan,
returns the identifier set in the tool’s settings dialog box in the id_string variable (otherwise empty string).
Not working on annotation elements (e.g. Label, D/W Marker, Zone Stamp).
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Full_ID_of_parent, "", id_string)


For annotation elements linked or hotlinked on the floo r plan,
returns all identifiers (Master ID) of the linked modules and the parent library parts’
identifier set in the tool’s settings dialog box in the id_string variable (otherwise empty string).
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Name_of_plan", "", name)

Returns in the given variable the name of the current project.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Story", "", index, story_name)

Returns in the index and story_name variables the index and the name of the current story. Should be used on floorpan only, as “current story” is not defined in other view types.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Home_story", "", index, story_name)

Returns in the index and story_name variables the index and the name of the home story.

n = REQUEST ("Home_story_of_opening", "", index, story_name)


Returns the index and the name of the home story of the opening in the index and story_name variables.
The home story is the first story, where the opening is visible.
Can be used in scripts of doors, windows, wallends, corner windows and skylights, and in the script of their labels and markers.
Causes warning if used in parameter script.

n = REQUEST ("Story_info", expr, nStories, index1, name1, elev1, height1 [, index2, name2, ...])

Returns the story information in the given variables: number of stories and story index, name, elevation, height to next successively.
If expr is a numerical expression, it means a story index: only the number of stories and the information on the specified story is returned.
If expr is a string expression, it means that information on all stories is requested.
The return value of the function is the number of successfully retrieved values.

Example 2:

DIM t[]
n = REQUEST ("STORY_INFO", "", nr, t)
FOR i = 1 TO nr
    nr = STR ("%.0m", t [4 * (i - 1) + 1])
    name = t [4 * (i - 1) + 2]
    elevation = STR ("%m", t [4 * (i - 1) + 3])
    height = STR ("%m", t [4 * (i - 1) + 4])
    TEXT2 0, -i, nr + "," + name + "," + elevation + "," + height
NEXT i


With the following requests, you can learn the dimension formats set in the Options/Project Preferences/Dimensions and Calculation Units & Rules dialog boxes.
These requests return a format string that can be used as the first parameter in the STR () function.

n = REQUEST ("Linear_dimension", "", format_string)
n = REQUEST ("Angular_dimension", "", format_string)


Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Angular_length_dimension", "", format_string)


Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Radial_dimension", "", format_string)


Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Level_dimension", "", format_string)


Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Elevation_dimension, "", format_string)


Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Window_door_dimension", "", format_string)
n = REQUEST ("Sill_height_dimension", "", format_string)
n = REQUEST ("Area_dimension", "", format_string)
n = REQUEST ("Calc_length_unit", "", format_string)
n = REQUEST ("Calc_area_unit", "", format_string)


Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Calc_volume_unit", "", format_string)
n = REQUEST ("Calc_angle_unit", "", format_string)


Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

Example 3:

format = ""
num = 60.55
n = REQUEST ("Angular_dimension", "",format) !"%.2dd"
TEXT2 0, 0, STR (format, num) !60.55
n = REQUEST ("Clean_intersections", "", state)


Returns the state of the Clean Wall & Beam Intersections feature (1 when turned on, 0 when off)
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Zone_category", "", name, code)

For zones, returns the name and the code string of the current zone category.

n = REQUEST ("Zone_relations", "", category_name, code, name, number [, category_name2, code2, name2, number2])


Returns in the given variables the zone category name and code and the name and number of the zone
where the library part containing this request is located. For doors and windows, there can be a maximum of two zones.
The return value of the request is the number of successfully retrieved values (0 if the library part is not inside any zone).

n = REQUEST ("Zone_relations_of_owner", "", category_name, code, name, number [, category_name2, code2, name2, number2])


Returns in the given variables the category name & code and the zone name & number of the zone
where the owner of the object is located. So, it is meaningful, if the library part has owner (door-window labels and door-window markers, etc.).
In case of a door label, its owner is the door. For doors and windows, there can be a maximum of two related zones.
The return value of the request is the number of successfully retrieved values
(0 if the object has no owner, or its owner is not inside any zone).
Causes warning if used in parameter script.

n = REQUEST ("Zone_colus_area", "", area)


Returns in the area variable the total area of the columns placed in the current zone. Effective only for Zone Stamps.
Available only for compatibility reasons. It is recommended to use quantities set in Zone Stamp fix parameters.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Custom_auto_label", "", name)


Returns in the name variable the name of the custom auto label of the library part or an empty string if it does not exist.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Rgb_of_material", name, r, g, b)
n = REQUEST ("Rgb_of_pen", penindex, r, g, b)
n = REQUEST ("Pen_of_RGB", "r g b", penindex)


Like the REQ() function (but in just one call),
returns in the specified variables the value of the r, g, b components of the material and pen,
or the index of the pen corresponding to the given RGB values.
All 3 expression return 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Height_of_style", name, height [, descent, leading])


Returns in the given variables the total height of the style measured in millimeters (height in meters is height / 1000 * GLOB_SCALE);
the descent (the distance in millimeters from the text base line to the descent line)
and the leading (the distance in millimeters from the descent line to the ascent line).

n = REQUEST ("Style_info", name, fontname [, size, anchor, face_or_slant])


Returns information in the given variables on the previously defined style
(see style parameters at the DEFINE STYLE command).
Can be useful in macros to collect information on the style defined in a main script.
Causes warning if used in parameter script.

n = REQUEST ("Name_of_material", index, name)

Returns in the variable the material name identified by index.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Name_of_building_material", index, name)

Returns in the variable the building material name identified by index.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Name_of_fill", index, name)

Returns in the name variable the fill name identified by index.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Name_of_line_type", index, name)

Returns in the given variable the line name identified by index.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Name_of_style", index, name)

Returns in the given variable the name of the style identified by index.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

If index < 0, it refers to a material, fill, line type or style defined in the GDL script or the MASTER_GDL file.
A call of a request with index = 0 returns in the variable the name of the default material or line type. (Empty string for fill and style.)

The return value of the request is the number of successfully retrieved values
(1 if no error occurred, 0 for error when the index is not valid).

n = REQUEST ("WINDOW_DOOR_SHOW_DIM", "", show)

Before 9.0 returns 1 in the show variable if Options/Display Options/Doors & Windows is set to “Show with Dimensions”, 0 otherwise.
Since 9.0 display options were split to separate Door and Window display options,
so for compatibility reasons checks if the request is used in a Window (or marker of a Window) or a Door (or marker of a Door)
and automatically returns the corresponding display option. In other cases (symbol, lamp, label) the Window option is returned.
Can be used to hide/show custom dimensions according to the current Display Options.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

Since 9.0 the “window_show_dim”, and the “door_show_dim” separate requests are available.

n = REQUEST ("window_show_dim", "", show)

Returns 1 in the show variable if in the Model View Options/Window options the “with Markers” is checked, 0 otherwise.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("door_show_dim", "", show)

Returns 1 in the show variable if in the Model View Options/Door options the “with Markers” is checked, 0 otherwise.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("name_of_listed", "", name)

Returns in the name variable the name of the library part associated with the property type library part containing this request.
For elements (Walls, Slabs, etc.), the name is an empty string.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("window_door_zone_relev", "", out_direction)

Effective only for Doors and Windows. Use it as complement to the “zone_relations” request.
Returns 1 in the out_direction variable if the Door/Window opening direction is in that of the first room identified by the “zone_relations” request,
2 if the opening direction is towards the second room. It also returns 2 if there is only one room and the opening direction is to the outside.
Causes warning if used in parameter script.

n = REQUEST ("window_door_zone_relev_of_owner", "", out_direction)

Effective only if the library part’s parent is a door or a window (markers, labels).
Use it as a complement to the “zone_relations_of_owner” request.
Returns 1 in the out_direction variable
if the parent’s opening direction is in that of the first zone identified by the zone relations type requests,
2 if the opening direction is towards the second zone. It also returns 2 if there is only one zone and the opening direction is to the outside.
Causes warning if used in parameter script.

n = REQUEST ("matching_properties", type, name1, name2, ..)

If type = 1, returns in the given variables individually associated property library part names, otherwise property library
part names associated by criteria. If used in an associative label,
the function returns the properties of the element the label is associated with.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Working_length_unit", "", format_string) n = REQUEST ("Working_angle_unit", "", format_string)

With these requests, the user can get the working unit formats as set in the Options > Project Preferences > Working Units dialog box.
They return a format string that can be used as the first parameter in the STR () function.
The requests both work when interpreting the user interface script.
“Working_angle_unit” causes warning if used in parameter script.

n = REQUEST ("Model_length_unit", "", format_string)

n = REQUEST ("Layout_length_unit", "", format_string)

With these requests, the user can get the layout and the model unit formats as set in the Options > Project Preferences >
Working Units dialog box. They return a format string that can be used as the first parameter in the STR () function.
The requests work only when interpreting the user interface scripts, and cause warning if used in parameter script.

n = REQUEST ("Model_text_size_unit", "", format_string)
n = REQUEST ("Layout_text_size_unit", "", format_string)

With these requests, the user can get the layout and the model text size formats.
They return a format string that can be used as the first parameter in the STR () function.
The requests work only when interpreting the user interface scripts.
Both expressions returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("Properties_Of_Parent", propertyType, parentProperties)

Compatibility: Introduced in ARCHICAD 20
Returns the properties of the parent object. All properties are returned in one array with the following form: ID, type, group, name. Can be used only in labels.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

Core property:   [id,    "",               "",           PropertyName]
AC property:     [guid,  "",               "GroupName",  PropertyName]
IFC property:    [id,    "IFC",            "GroupName",  PropertyName]
Classification:  [guid,  "Classification", "",           PropertyName]
propertyType: keyword defining the type of the requested properties. Empty string retruns all types of properties. Possible values:
COREPROPERTY
ACPROPERTY
IFCPROPERTY
CLASSIFICATION

Compatibility: the request is introduced in ARCHICAD 20. The property type options and the Classification property type are introduced in ARCHICAD 21.

Example 4:

DIM parentProperties[]
n = REQUEST ("Properties_Of_Parent", "", parentProperties)
! parentProperties =   [Id1, TypeName1, GroupName1, PropertyName1,
Id2, TypeName2, GroupName2, PropertyName2,
...
Idn, TypeNamen, GroupNamen, PropertyNamen]

 

n = REQUEST ( "Property_Value_Of_Parent", "id", type, dim1, dim2, propertyValues)

Compatibility: Introduced in ARCHICAD 20
Returns value array of the selected property. Can be used only in labels.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

id: the ID of the selected property (string).
type: the type of the selected property value.
1: boolean
2: integer
3: real number
4: string
dim1, dim2: the dimensions of the propertyValues array.
dim1 = 0, dim2 = 0: simple, scalar value.
dim1 > 0, dim2 > 0: list of values.

Example 5:

DIM propertyValues[]
n = REQUEST ("Property_Value_Of_Parent", "ExampleId", type, dim1, dim2, propertyValues)
n = REQUEST ("Property_Name", "id", typeName, groupName, propertyName)

Compatibility: Introduced in ARCHICAD 20
Returns the type, group and name of the selected property. Can be used only in labels.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

id: the ID of the selected property (string).
typeName: the Type of the selected property (string).
"IFC": for IFC properties
"": other properties
groupName: the Group of the selected property (string).
empty string (“”) for Core properties.
propertyName: the Name of the selected property (string).

 

n = REQUEST ("AUTOTEXT_LIST", "", autoTextListArray)

Compatibility: Introduced in ARCHICAD 20
Returns one AUTOTEXT array of the autotexts used in the project with the following triplets [“ID”, “Category”, “Name”].
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.
Can be used only in UI script. The ID is stored in the parameter via the UI_CUSTOM_POPUP… commands. Contains all autotexts from Project Info and Autotext Dialog (Text tool – Insert Autotext).

Example 6:

DIM autoTextListArray[]
n = REQUEST ("AUTOTEXT_LIST", "", autoTextListArray)
! autoTextListArray =   [ID1, CategoryName1, TextName1,
                         ID2, CategoryName2, TextName2,
                         ...
                         IDn, CategoryNamen, TextNamen]

 

n = REQUEST{3} ("Sum_with_rounding", req_name, addends_array, result)

Compatibility: Introduced in ARCHICAD 20
Returns the sum of the numbers in addends_array, with rounding according to the “Calculate Totals by” project preference. This preference can be found in Options/Project Preferences/Calculation Units & Rules.
Possible project preference settings:

  • “Displayed values”: the request will first round the addends according to req_name, and then sum them.
  • “Exact values”: the request will simply sum the addends.

Causes warning if used in parameter script.
Return values:

  • 0, if req_name is invalid.
  • 1, if the call succeeded.
req_name: the name of the formatting request specifying how the addends have to be rounded if “Calculate Totals by” is set to “Displayed values”.For example if req_name = “Area_dimension”, and the Options/Project Preferences/Dimensions/Area Calculations is set to “square centimeter” with 3 decimals, rounding to 0.025, then the addends will be rounded to the multiples of 0.025 cm2, that is to 0.0000025 m2.
Valid request names:
Linear_dimension, Angular_dimension, Radial_dimension, Level_dimension, Elevation_dimension, Window_door_dimension, Sill_height_dimension, Area_dimension, Calc_length_unit, Calc_area_unit, Calc_volume_unit, Calc_angle_unit.
addends_array: the array of numbers to be added. Whether they have to be treated as m, m2, m3 or degrees is determined by req_name.
result: a number, on return it will be set to the sum of the addends according to the “Calculate Totals by” preference. Note that result is in the same unit as the addends. It is not converted to the target unit specified by req_name.

 

n = REQUEST ("ASSOCLP_PARVALUE", expr, name_or_index, type, flags, dim1, dim2, p_values)
n = REQUEST ("ASSOCLP_PARVALUE_WITH_DESCRIPTION", expr, name_or_index, type, flags, dim1, dim2, p_values_and_descriptions)

Returns information in the given variables on the library part parameter with which the library part containing this request is associated.
Can be used in property objects, labels and marker objects. “ASSOCLP_PARVALUE_WITH_DESCRIPTION” causes warning if used in parameter script.

The function return value is the number of successfully retrieved values, 0 if the specified parameter does not exist or an error occurred.

expr: the request’s object, associated library part parameter name or index expression.
name_or_index:
returns the index or the name of the parameter, depending on the previous expression type
(returns index if a parameter name, name if the index is specified).
type: parameter type, possible values:
1: boolean
2: integer
3: real number
4: string
5: length
6: angle
7: line
8: material
9: fill
10: pen color
11: light switch
12: rgb color
13: light intensity
14: separator
15: title
16: building material
flags:
flags = j1 + 2*j2 + 64*j7 + 128*j8, where each j can be 0 or 1.
j1: child/indented in parameter list
j2: with bold text in parameter list
j7: disabled (locked in all contexts)
j8: hidden in the parameter list
dim1, dim2: dim1 is the number of rows, dim2 the number of columns.
dim1 = 0, dim2 = 0: simple, scalar value
dim1 > 0, dim2 = 0: one dimensional array
dim1 > 0, dim2 > 0: two dimensional array
If dim2 > 0, then dim1 > 0.
p_values:
for ASSOCLP_PARVALUE returns the parameter value or array of values. The array elements are returned successively,
row by row as a one dimensional array, independently of the dimensions of the variable specified to store it.
If the variable is not a dynamic array, there are as many elements stored as there is room for
(for a simple variable only one, the first element). If values is a two dimensional dynamic array, all elements are stored in the first row(as specified at the VALUES command).
p_values_and_descriptions:
for ASSOCLP_PARVALUE_WITH_DESCRIPTION returns the parameter value followed by the parameter description string
(as specified at the VALUES command command) or an array of these pairs.
For string type parameters the description string is always empty.
The array element – array element description string pairs are returned successively,
row by row as a one dimensional array, independently of the dimensions of the variable specified to store it.
If the variable is not a dynamic array, there are as many elements stored as there is room for
(for a simple variable only one, the first element). If values is a two dimensional dynamic array, all elements are stored in the first row.
n = REQUEST ("ASSOCLP_NAME", "", name)

Returns in the given variable the name of the library part associated with the label or marker object.
For elements (Walls, Slabs, etc.) the name is an empty string.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("ASSOCEL_PROPERTIES", parameter_string, nr_data, data)

Returns, in the given variables,
own property data or the element properties which the library part containing this request is associated to
(in labels and associative marker objects).
The function return value is the number of successfully retrieved values, 0 if no property data was found or an error occurred.
The function does not work in property objects during the listing process.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

parameter_string:
a combination of keywords separated by commas representing the requested fields of the property data records.
Records will be ordered accordingly. Possible values:
"ISCOMP"
"DBSETNAME"
"KEYCODE"
"KEYNAME"
"CODE"
"NAME"
"FULLNAME"
"QUANTITY"
"TOTQUANTITY"
"UNITCODE"
"UNITNAME"
"UNITFORMATSTR"
"PROPOBJNAME"
nr_data: returns the number of the data items.
data:
returns the property data, records containing and being ordered by the fields specified in the parameter string.
Values are returned as a one dimensional array which contains the requested record fields successively,
independently of the dimensions of the variable specified to store it. If the variable is not a dynamic array,
there are as many elements stored as there is room for (in case of a simple variable only one, the first element).
If values is a two dimensional dynamic array, all elements are stored in the first row.

Example 7:

DIM DATA []
n = REQUEST ("ASSOCEL_PROPERTIES", "iscomp, code, name", nr, data)
IF nr = 0 THEN
    TEXT2 0, 0, "No properties"
ELSE
    j = 0
    FOR i = 1 TO nr
        IF i MOD 3 = 0 THEN
            TEXT2 0, -j, DATA  ! name
            j = j + 1
        ENDIF
    NEXT i
ENDIF

 

n = REQUEST ("REFERENCE_LEVEL_DATA", "", name1, elev1, name2, elev2, name3, elev3, name4, elev4)


Returns in the given variables the names and elevations of the reference levels as set in the Options/Project Preferences/Reference Levels dialog.
The function return value is the number of successfully retrieved values, 0 if an error occurred.

n = REQUEST ("ANCESTRY_INFO", expr, name [, guid, parent_name1, parent_guid1, ... parent_namen, parent_guidn)


Ancestry information on a library part.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.


If expr = 0, returns in the given variables the name and the globally unique identifier of the library part containing this request function.
Optionally the function returns the names and globally unique identifiers of the parents of the library part (parent_namei, parent_guidi).
If the parent templates are not loaded their names will be empty strings.


If expr = 1, returns information on the library part replaced by the template containing this function.
In this case if the template is not actually replacing, no values are returned.

The return value of the request is the number of successfully retrieved values.

Example 8:

DIM strings[]
n = REQUEST ("ANCESTRY_INFO", 1, name, guid, strings)
IF n > 2 THEN
    ! data of replaced library part
    TEXT2 0, -1, "replacing: " + name + ' ' + guid
    ! parents
    l = -2
    FOR i = 1 TO n - 2 STEP 2
        TEXT2 0, l, strings [ i ]
        l = l - 1
    NEXT i
ENDIF

 

n = REQUEST ("TEXTBLOCK_INFO", textblock_name, width, height)


Returns in the given variables the sizes in x and y direction of a text block previously defined via the TEXTBLOCK command.
The sizes are in mm or in m in model space depending on the fixed_height parameter value of TEXTBLOCK
(millimeters if 1, meters in model space if 0 ). If width was 0, the request returns the calculated width and height,
if width was specified in the text block definition, returns the calculated height corresponding to that width.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST{2} ("Material_info", name_or_index, param_name, value_or_values)

Returns information in the given variable(s) on a parameter (or extra parameter, see the section called “Additional Data”) of the specified material.
RGB information is returned in three separate variables, texture information is returned in the following variables:
file_name, width, height, mask, rotation_angle corresponding to the texture definition.
All other parameter information is returned in single variables.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.
Possible material parameter names corresponding to parameters of the material definition:

param_name:
"gs_mat_surface_rgb": surface R, G, B [0.0..1.0]
"gs_mat_surface_r": surface R [0.0..1.0]
"gs_mat_surface_g": surface G [0.0..1.0]
"gs_mat_surface_b": surface B [0.0..1.0]
"gs_mat_ambient": ambient coefficient [0.0..1.0]
"gs_mat_diffuse": diffuse coefficient [0.0..1.0]
"gs_mat_specular": specular coefficient [0.0..1.0]
"gs_mat_transparent": transparent coefficient [0.0..1.0]
"gs_mat_shining": shininess [0.0..100.0]
"gs_mat_transp_att": transparency attenuation [0.0..4.0]
"gs_mat_specular_rgb": specular color R, G, B [0.0..1.0]
"gs_mat_specular_r": specular color R [0.0..1.0]
"gs_mat_specular_g": specular color G [0.0..1.0]
"gs_mat_specular_b": specular color B [0.0..1.0]
"gs_mat_emission_rgb": emission color R, G, B [0.0..1.0]
"gs_mat_emission_r": emission color R [0.0..1.0]
"gs_mat_emission_g": emission color G [0.0..1.0]
"gs_mat_emission_b": emission color B [0.0..1.0]
"gs_mat_emission_att": emission attenuation [0.0..65.5]
"gs_mat_fill_ind": fill index
"gs_mat_fillcolor_ind": fill color index
"gs_mat_texture": texture index

Example 9:

n = REQUEST{2} ("Material_info", "Brick-Face", "gs_mat_ambient", a)
n = REQUEST{2} ("Material_info", 1, "gs_mat_surface_rgb", r, g, b)
n = REQUEST{2} ("Material_info", "Brick-Face", "gs_mat_texture",
            file_name, w, h, mask, alpha)
n = REQUEST{2} ("Material_info", "My-Material", "my_extra_parameter", e)

 

n = REQUEST{2} ("Building_Material_info", name_or_index, param_name, value_or_values)


Returns information in the given variable(s) on a parameter of the specified building material.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.
Possible building material parameter names corresponding to parameters of the building material definition:

param_name:
"gs_bmat_id": building material id
"gs_bmat_surface": building material surface index
"gs_bmat_description": building material description
"gs_bmat_manufacturer": building material manufacturer
"gs_bmat_collisiondetection": building material participates in collision detection (0 or 1)
"gs_bmat_intersectionpriority": building material intersection priority
"gs_bmat_cutfill_properties": building material cut fill properties (cut fill index number, cut fill foreground pen index number, cut fill background pen index number)
"gs_bmat_physical_properties": building material physical properties (thermal conductivity, density, heat capacity, embodied energy, embodied carbon)

Example 10:

n = REQUEST{2} ("Building_Material_info", "Brick", "gs_bmat_id", id)
n = REQUEST{2} ("Building_Material_info", "Brick", "gs_bmat_surface", index)
n = REQUEST{2} ("Building_Material_info", "Brick", "gs_bmat_physical_properties",
            thermalConductivity, density, heatCapacity, embodiedEnergy, embodiedCarbon)

 

n = REQUEST ("FONTNAMES_LIST", "", fontnames)


Returns in the given variables the fontnames available on the current computer (with character codes included).
This list (or any part of this list) can be used in a VALUES command to set up a fontname popup.
The function return value is the number of successfully retrieved values, 0 if an error occurred.

Example 11:

dim fontnames[]
n = REQUEST ("FONTNAMES_LIST", "", fontnames)
VALUES "f" fontnames, CUSTOM


This form of the VALUES command assembles a fontnames pop-up for the simple string-typed parameter “f”. The “fontnames” variable contains the possible fontnames (with character codes included) which can be set manually or using the REQUEST (“FONTNAMES_LIST”, …) command.
The CUSTOM keyword is necessary for the correct handling of missing fonts on other platforms/computers:
if it is specified, a fontname set on another platform/computer missing in the current environment will be preserved in the parameter settings as a custom value (otherwise, due to the implementation of the VALUES command, a missing string popup value in the parameter settings will be replaced with the first current string value).
It is recommended to include this function in the ArchiCAD_Library_Master file to get the value list once, or use it only in User Interface script in combination with UI_CUSTOM_POPUP_INFIELD to avoid value list altogether.

n = REQUEST ("HomeDB_info", "", homeDBIntId, homeDBUserId, homeDBName, homeContext)

Returns in the given variables the internal ID (integer),
the user ID and name (strings) of the home database (where the library part containing this request was placed).

  • if placed on the floor plan: the story internal ID, index as a string and name, homeContext = 1,
  • if placed on a section: the section internal ID, reference ID and name, homeContext = 2,
  • if placed on a detail: the detail internal ID, reference ID and name, homeContext = 3,
  • if placed on a master layout: the layout internal ID, empty string and name, homeContext = 4,
  • if placed on a layout: the layout internal ID, number and name, homeContext = 5.

For labels the returned data refers to the labeled element.
The collected data can be used to uniquely identify elements in different databases of a plan file.
Causes warning if used in parameter script.

n = REQUEST ("floor_plan_option", "", storyViewpointType)

Returns the story viewpoint type which is set in the Model View Options.
0 stands for “Floor Plan”, 1 stands for “Ceiling Plan”.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

n = REQUEST ("class_of_fill", index, class)

Returns class of the fill identified by index in the class variable. Causes warning if used in parameter script.

class: Possible values:
1: vector fill
2: symbol fill
3: translucent fill
4: linear gradient fill
5: radial gradient fill
6: image fill
n = REQUEST ("view_rotangle", "", angleViewRotation)

Returns the rotation angle of the current view set in Oriented view option of ARCHICAD. Causes warning if used in parameter script.

n = REQUEST ("program_info", "", name[, version[, keySerialNumber[, isCommercial]]])

Returns information on the currently running program. Causes warning if used in parameter script.

name: name of the program
version: version number of the program
keySerialNumber: serial number of the keyplug
isCommercial: returns true if there is running a full (commercial) version of the program
n = REQUEST ("Configuration_number", "", stConfigurationNumber)

Returns the configuration number (as string expression) assigned to the current ARCHICAD license in case of soft license or hardware key. Returns empty string in case of Edu, Trial or Demo licenses. Each configuration number is unique and does not change.
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.
Compatibility: Introduced in ARCHICAD 20

n = REQUEST (extension_name, parameter_string, variable1, variable2, ...)

If the question isn’t one of those listed above, the REQUEST() function will attempt to use it as an extension-specific name.
If this extension is loaded, it will be used to get as many variable names as are specified.
The parameter string is interpreted by the extension.

n = REQUEST ("COMPONENT_PROJECTED_AREA", idxSkin, projectedArea)

Returns the projected area of the indexed skin. Available in property script only (other scripts return 0).
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

idxSkin: Possible values:
0: for basic elements
1- : index of the skin in composites
1- : index of the component in profiles

Example 12:

n = REQUEST ("COMPONENT_PROJECTED_AREA", 0, a)
COMPONENT "Projected Area", a, "m2"

Used in property script, first request the area of the skin, then create a component using the returned value.

n = REQUEST ("COMPONENT_VOLUME", idxSkin, skinVolume)


Returns the volume of the indexed skin/component. Available in property script only (other scripts return 0).
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

idxSkin: Possible values:
0: for basic elements
1- : index of the skin in composites
1- : index of the component in profiles

Example 13:

n = REQUEST ("COMPONENT_VOLUME", 0, v)
COMPONENT "Volume", v, "m3"

Used in property script, first request the volume of the skin, then create a component using the returned value.

n = REQUEST ("DateTime", format_string, datetimestring)

Returns the current date and time as a formatted string in datetimestring. Uses the DateTime Add-On, opening and closing the required channel.

format_string: Format string, described at paramString parameter of “Opening Channel”.
datetimestring: The formatted string is returned in this variable

The requests cause warning if used in parameter script.

Profile Requests

n = REQUEST ("Name_of_Profile", index, name)
Returns in the name variable the profile name identified by index. Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.

Compatibility: introduced in ARCHICAD 21.

n = REQUEST ("Profile_components", name_or_index, nComponents,
        compType1, compType2, ..., compTypen)
Returns the number (nComponents) and component types (compTypen) of the profile identified by name or index. Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.
compTypei Possible values of profile component types:
0: core
1: finish
2: other

Compatibility: introduced in ARCHICAD 21.

_nComponents = 0
dim _componentTypes[]
n = REQUEST ("Profile_components", myProfileIdx, _nComponents, _componentTypes
n = REQUEST ("Profile_default_boundingbox", name_or_index, xmin, ymin, xmax, ymax)
Returns the 2 defining coordinate point of the original bounding rectangle relative to the origo of the profile identified by name or index.

Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.
Compatibility: introduced in ARCHICAD 21.

n = REQUEST ("Profile_default_geometry", name_or_index, n1, n2, ..., nm,
            x11, y11, edgeVisible11, vertEdgeVisible11, additionalStatus11, ...,
            x1n1, y1n1, edgeVisible1n1, vertEdgeVisible1n1, additionalStatus1n1,
            x21, y21, edgeVisible21, vertEdgeVisible21, additionalStatus21, ...,
            x2n2, y2n2, edgeVisible2n2, vertEdgeVisible2n2, additionalStatus2n2, ...,
            xm1, ym1, edgeVisiblem1, vertEdgeVisiblem1, additionalStatusm1, ...,
            xmnm, ymnm, edgeVisiblemnm, vertEdgeVisiblemnm, additionalStatusmnm)
Returns the original geometric data of the profile identified by name or index. Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.
n1...ni: then number of contour nodes in each profile component. The total number of profile components (m) can be returned by the “Profile_components” request.
edgeVisiblei: contour starting from i node is visible.
vertEdgeVisiblei: vertical edge starting from i node is visible, usable in 3D (0 in case of segmented polygon).
additionalStatusi: used for segments and arcs of the polyline (set centerpoint = 900, arc using centerpoint and angle = 4000, etc.), or to mark the contour end control point (-1, this case the vertEdgeVisiblei and edgeVisiblei are set to 0 automatically).

The status parameters returned in this structure support different status type definitions of poly2, cprism, tube. Each format can be calculated with the following method:

poly2Status = edgeVisible + additionalStatus
prismStatus = additionalStatus
tubeStatus = additionalStatus
if additionalStatus >= 0 then         ! not contour end
    if edgeVisible then
        prismStatus = prismStatus + 15    ! j1, j2, j3, j4
    endif
    if verticalEdgeVisible = 0 then
        prismStatus = prismStatus+ 64     ! j7
        ! in tube, lateral edges starting from the node are used for showing the contour
        tubeStatus = tubeStatus + 1
    endif
endif

Compatibility: introduced in ARCHICAD 21.

n = REQUEST{4} ("Profile_component_info", name_or_index, component_ind, param_name, value)
Returns a requested attribute value of a dedicated component (by component_ind) of the profile identified by name or index. Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.
The component_ind must be in the valid range of nComponents (defined by “Profile_components” request).
param_name: addresses attribute settings of Profile Manager, returned in value
gs_profile_bmat: building material index of the component
gs_profile_surface: override surface index of the component (in case of active override settings; returns the surface of the building material otherwise)
gs_profile_showoutline: “Show Outline” setting of the component
gs_profile_outlinetype: “Outline Type” setting of the component
gs_profile_outlinepen: “Outline Pen” setting of the component

Return attribute values can be used in any attribute related command, such as the POLY2_B{6} command, where contour sections of the polygon can be customized individually.

Compatibility: introduced in ARCHICAD 21.

n = REQUEST{4} ("Profile_component_info", name_or_index, component_ind, param_name,
            value1, value2, ..., valuen)
Returns requested attributes of all edges in the dedicated component (by component_ind) of the profile identified by name or index. Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.
param_name: addresses attribute settings of Profile Manager, returned in >value
gs_profile_comp_surfaces: individual surface indexes of edges of the component
gs_profile_comp_pens: individual pen indexes of edges of the component
gs_profile_comp_linetype: individual linetype indexes of edges of the component
Return attribute values can be used in any attribute related command, such as the POLY2_B{6} command, where contour sections of the polygon can be customized individually.

Compatibility: introduced in ARCHICAD 21.

Deprecated requests

n = REQUEST ("Constr_Fills_display", "", optionVal)
optionVal: cut fill display code.
1: Show cut fill contours only (previous Empty)
2: Show cut fill contours only with separator lines (previous No Fills)
4: Cut fill patterns: Solid (previous Solid)
6: Cut fill patterns: as in Settings (previous Vectorial Hatching)

Returns in the given variable the value of the Cut Fills Display option as set in the Document/ Set Model View/ Model View Options
(previous Construction Fills).
Expression returns 0 and contains dummy return values (emtpy string or 0) if used in parameter script, causing additional warning.
Deprecated in ARCHICAD 20: the returned value will always be 6 by default (Cut fill patterns: as in Settings).

n = REQUEST ("Internal_ID", "", id)

Always returns 1. Use GLOB_INTGUID instead.