CC3+ contains a huge amount of various commands and features. This series highlights a number of these. There won't be any special progression to this series, and the command will be selected from the entire range, from the simple basic commands, to more advanced features intended for the more advanced users. Feel free to use this topic to discuss the command presented.
This series is called the command of the week, but it could also explain a feature. The explanations will tend to explain the technical parts of the command, and is intended to highlight the basics (and complexities) of the command, and information about how to use it, but won't be a detailed tutorial. It is up to you to use it creatively in your maps.

Week 32 - Get Extents

There are times when you need to get the size of your map, and use that data for something, for example in a macro. To get just the basic number, the DISTANCE command will often do, but if you need exact numbers for further processing, you'll want to use one of the variations of the Get Extents command. These commands can be used to get the raw values for width and height, or you can retrieve the coordinates of the lower left and upper right extent of your map.

Note that while the basic versions of these commands are available in any version, you need to have installed CC3+ Update 13 (Version 3.79) to get access to the commands that operate on specific layers and sheets.

Where to find them?

Command Line: GETEXTX, GETEXTY, GETEXTL, GETEXTH, GETSHEETL, GETSHEETH, GETSHEETY, GETSHEETX, GETLAYERL, GETLAYERH, GETLAYERY, GETLAYERX

How to use them

These commands are primarily intended to use in a macro, so you'll usually want to use them to assign a value to an appropriate variable. In the list above, all the commands that ends with X or Y returns a real value (length and height respectively), while those that ends with L or H returns the coordinates of a point (representing the lower left and upper right extent receptively).

The first four commands (GETEXTX, GETEXTY, GETEXTL, GETEXTH) require just a single parameter, the variable to store the result in. These four commands operate on the extents on the entire map (excluding hidden layers and sheets). Note that this also includes entities such as the screen which is used to hide entities that extend beyond the map border. That means that the values reported by these commands are generally a bit outside the visible map, and the length/height are a bit larger than the map itself.
- GETEXTX - Gets the width of the map
- GETEXTY - Gets the height of the map
- GETEXTL - Gets the coordinates of the lower left corner of the map
- GETEXTH - Gets the coordinates of the upper right corner of the map.

The next four commands (GETSHEETL, GETSHEETH, GETSHEETY, GETSHEETX) are just like the first four, except that in addition to a variable, it also require a parameter that is the name of a sheet in the map. Instead of getting values for the extent of all entities in the map, it only considers the entities on the sheet specified.

The last four commands (GETLAYERL, GETLAYERH, GETLAYERY, GETLAYERX) are also the same as the four above, but these operate on the specified layer.

Note that when CC3+ calculates the extents of a map, it looks at all the entities on the map (or on a particular sheet/layer if using those versions of the commands) and figures out where the leftmost entity is, where the rightmost one is, where the topmost one is, and where the bottommost one is. So, the width of the map is the length between the outside edge of the leftmost entity and outside edge of the rightmost entity (only considering the left-right distance (x-axis), ignoring differences in the up-down (y) axis). The height will be calculated the same way. Similarly, the bottom left coordinate is made taking the x coordinate of the outer edge of the leftmost entity and the y coordinate of the bottom edge of the lowest entity. This means that it doesn't have to be an actual entity at that coordinate, but rather that a bounding rectangle drawn using the two coordinates (bottom left and upper right) will encompass all the entities in the map (or sheet/layer)

Examples

Get the width of the map and store it in the rWidth variable:
GETEXTX rWidth

Get the lower-left coordinate of the SYMBOLS sheet and store it in xyPoint.
GETSHEETL xyPoint SYMBOLS

Get both the lower left and upper right coordinate of the MAP BORDER layer, and stores it in the xy1 and xy2 variables. These coordinates are particularity interesting, because the entities on the map border defines the extent of the actual map in most cases, which is usually exactly what you want.
GETLAYERL xy1 MAP BORDER GETLAYERL xy2 MAP BORDER

Known Issues

The values returned by these commands are very hard to work with if the unit display in the map is set to 'Fractional Inches' or 'Feet and Inches'. If you do macro work using these commands, I STRONGLY suggest running the DISTFMT 0 command first. This changes the unit display to numeric, avoiding all issues. Note that unfortunately, it is not presently possible to return the unit format to the prior value automatically, but it is only a display format, so it won't have any effect on the map.

Related Commands

ZOOML and ZOOMS are variants of the ZOOMEXT command, but that zooms to the extents of the specified sheet or layer respectively.