こんにちは！SolidWorksの自動化の世界へようこそ。
これまで「マクロの記録」ボタンを押して生成されたコードを眺め、「なんだかよく分からないけれど動くからいいか」と放置していませんでしたか？
おめでとうございます。今日、あなたはその「思考停止のマクロ記録」を卒業し、SolidWorks APIの深淵に踏み込むエンジニアへの第一歩を踏み出します。
実務でアセンブリの自動化（特に`AddMate5`メソッドを使った合致のプログラム生成）を行うとき、最も頭を悩ませるのが「なぜか合致がエラーになる」という現象です。画面の前で「あれ？ 参照面が違う？ 向きが逆？」と頭を抱えた経験、ありませんか？
今回は、`AddMate5`が返す魔術的な戻り値`MateErrorStatus`を完全に手なずけ、エラーの原因を瞬時に特定してログに出力する「プロのトラブルシューティング術」を伝授します。ここをクリアすれば、あなたのVBAスキルは一気に実務レベルへ到達しますよ。ついてきてくださいね！
—
1. なぜ「マクロの記録」だけでは実務を突破できないのか？
アセンブリの自動化において、2つの部品を組み付ける（合致させる）処理は花形です。
しかし、APIのヘルプを見ると、合致を作成するメソッドにはいくつか種類があります。その中でも最も強力で、現代のSolidWorks APIの標準となっているのが `IAssemblyDoc::AddMate5` です。
ここで、初学者が最初にハマる罠があります。
「コードを実行したのに、SolidWorksが『合致を作成できませんでした』と警告を出して止まってしまう。プログラムもそこで強制終了してしまう…」
マクロの記録は「うまくいった瞬間」しか記録してくれません。しかし、実務の現場では、「部品の選択ミス」「幾何公差の矛盾」「名前の変更による参照迷子」などにより、合致が失敗するリスクが常に隣り合わせです。
失敗したときにプログラムがフリーズしたり、闇雲にエラーを出したりするのではなく、「どこがダメだったのか」をプログラム自身が判断し、ログに残して优雅（ゆうが）に処理を継続する。これこそが、一流のエンジニアが書くマクロの条件なのです。
—
2. `AddMate5`の戻り値 `MateErrorStatus` とは何か？
`AddMate5`メソッドは、ただ合致を作るだけではありません。実行結果として、「何が原因で失敗したのか（あるいは成功したのか）」を示すステータスコード（整数値）」をこっそりと返してくれます。
これが `MateErrorStatus` です。
主なステータスの一例を覗いてみましょう。
- `swMateError_NoError` (0): 大成功！完璧です。
- `swMateError_BadEntity` (1): 選択した面やエッジ（エンティティ）が無効です（消滅している、または選択ミス）。
- `swMateError_EntitiesAreParallel` (2): 平行にしてはいけないのに平行になっている等、幾何学的矛盾です。
- `swMateError_CoincidentWithEdge` (3): エッジに対する一致など、不適切な組み合わせです。
- (※他にも多数のステータスが存在します)
つまり、この戻り値を `Select Case`構文などで受け取って解析してやれば、「あ、今回は面が平行になっちゃってエラーだな」とプログラム側で知ることができるわけです。
—
3. 【実践】合致エラーを自動解析してログに出力するVBAコード
百聞は一見に如かず。実際に動かせる実用的なコードを用意しました。
このコードは、指定した2つの面（あるいは部品）に対して同軸心合致（Concentric）を試み、もし失敗したら、その理由をイミディエイトウィンドウ（およびテキストファイル）にログ出力するものです。
開発環境（VBAエディタ）を開き、標準モジュールに貼り付けてみてください。
Option Explicit
‘ ==============================================================================
‘ 【実務中級】AddMate5の戻り値を解析してログ出力するサンプルマクロ
‘ ==============================================================================
Sub AutoMateWithLogging()
Dim swApp As SldWorks.SldWorks
Dim swAssm As SldWorks.AssemblyDoc
Dim swModel As SldWorks.ModelDoc2
Set swApp = Application.SldWorks
Set swModel = swApp.ActiveDoc
‘ アクティブドキュメントがアセンブリかチェック
If swModel Is Nothing Then
MsgBox “ドキュメントが開かれていません。”, vbCritical
Exit Sub
End If
If swModel.GetType <> swDocASSEMBLY Then
MsgBox “アクティブなドキュメントがアセンブリではありません。”, vbCritical
Exit Sub
End If
Set swAssm = swModel
‘ — 【前提】あらかじめ画面上で合致させたい2つのエンティティ（面や軸）が
‘ — 選択されている状態を想定しています。
Dim mateType As Long
Dim align As Long
Dim flipped As Boolean
Dim distance As Double
Dim distanceUpperBound As Double
Dim distanceLowerBound As Double
Dim errorStatus As Long ‘ ← ここにエラーのステータスが格納されます！
‘ 定数の定義 (swMateType_e)
‘ swMateCONCENTRIC = 4 (同軸心)
‘ swMateAlign_ALIGNED = 0 (公称)
mateType = 4 ‘ 同軸心合致
align = 0
distance = 0
distanceUpperBound = 0
distanceLowerBound = 0
‘ AddMate5の実行
‘ 引数の詳細：
‘ MateType, Alignment, Flip, Distance, DistUpper, DistLower,
‘ LockRotation, GearRatio1, GearRatio2, UseLimits1, UseLimits2, ErrorStatus
Dim swMateRet As SldWorks.Mate2
Set swMateRet = swAssm.AddMate5( _
mateType, _
align, _
False, _
distance, _
distanceUpperBound, _
distanceLowerBound, _
0, 0, 0, 0, 0, _
errorStatus)
‘ 戻り値（errorStatus）を判定してログ出力
Call OutputMateResultLog(errorStatus, “軸と穴の同軸心合致”)
End Sub
‘ ==============================================================================
‘ ログ出力とエラー解析を行うサブルーチン
‘ ==============================================================================
Sub OutputMateResultLog(ByVal errStatus As Long, ByVal mateDescription As String)
Dim logMessage As String
Dim isSuccess As Boolean
Select Case errStatus
Case 0 ‘ swMateError_NoError
logMessage = “【SUCCESS】 ” & mateDescription & ” の合致に成功しました。”
isSuccess = True
Case 1 ‘ swMateError_BadEntity
logMessage = “【ERROR: 1】 ” & mateDescription & ” – 無効なエンティティ（面・エッジ）が選択されました。部品が削除されたか、選択ミスです。”
isSuccess = False
Case 2 ‘ swMateError_EntitiesAreParallel
logMessage = “【ERROR: 2】 ” & mateDescription & ” – ジオメトリの矛盾（平行エラーなど）が発生しました。”
isSuccess = False
Case 3 ‘ swMateError_CoincidentWithEdge
logMessage = “【ERROR: 3】 ” & mateDescription & ” – エッジに対する不適切な一致合致です。”
isSuccess = False
Case Else
logMessage = “【ERROR: ” & errStatus & “】 ” & mateDescription & ” – 予期せぬエラーコードを検知しました。”
isSuccess = False
End Select
‘ 1. イミディエイトウィンドウに出力 (Ctrl + G で確認)
Debug.Print Now & ” : ” & logMessage
‘ 2. メッセージボックスでユーザーに通知（必要に応じてファイル出力に拡張可能）
If isSuccess Then
‘ 成功時は静かに進む（大量処理の邪魔にならないように）
Else
MsgBox logMessage, vbExclamation, “合致エラー検出”
‘ ここでテキストファイル（TextStream等）にログを書き出す処理を追加すると完璧です
End If
End Sub
—
4. コードのここがポイント！実務で生きる知見
上記のコードで、特に注目してほしいポイントを解説します。
1. ByRefで渡される `errorStatus` 変数
`AddMate5`の最後の引数に変数（上記のコードでは `errorStatus`）を渡しています。VB/VBAの仕様により、この変数にはメソッド内部で「結果のコード」が上書きされて返ってきます（参照渡し）。これを `Select Case` でキャッチするのが、エラーハンドリングの王道パターンです。
2. 大量処理（ループ処理）への応用性
数十個、数百個の部品を自動で組み立てるスクリプトを書くとき、途中でエラーが起きてマクロが止まってしまうと、どこまで処理が進んだ分からなくなって絶望します。しかし、このようにエラーを数値で捕らえ、テキストログやイミディエイトウィンドウに「どの合致で、どのエラーコードが出たか」を吐き出す仕組みを作っておけば、「あ、15個目のボルトの穴の選択がズレてたんだな」と後から一発で特定できます。
—
5. まとめと次のステップ
お疲れ様でした！
今回は、`AddMate5` の戻り値 `MateErrorStatus` を使った、プロ仕様の動的エラー判定とログ出力のテクニックを解説しました。
ここをクリアしたあなたなら、単に「動くマクロ」を作るだけでなく、「現場でトラブルが起きても自己解決できる堅牢な自動化ツール」を設計できるようになっています。
「マクロの記録」という安全な遊園地を出て、APIという広大な海原へ漕ぎ出す第一歩としては、これ以上ない経験になったはずです。
次回のテーマでは、このエラーログを画面に出すだけでなく、PCのデスクトップに自動で `.txt` ファイルとしてタイムスタンプ付きで出力する「ファイル出力の実装テクニック」を深掘りしていきましょう。
ここをクリアすれば、SolidWorks VBAの基本はバッチリですよ。明日からの設計業務効率化に、ぜひこの知見を役立ててください。それでは、また次のエンジニアリングでお会いしましょう！
